feat(server): migrate /controls + /control-templates onto auth framework

Mirrors #204's bindings migration: replaces require_admin_key and
router-level require_api_key with require_operation(CONTROLS_*) on
every protected route on /controls and on /control-templates/render.
Both routers now mount with the non-validating
get_api_key_from_header so the framework owns authentication and
authorization, with the extractor attached purely so the generated
OpenAPI advertises X-API-Key.

GET /controls/schema is intentionally left without a
require_operation dependency: it returns a static model schema with
no tenant state and routing it through the framework would force the
upstream provider to handle a meta-only operation that has no
permission semantics.

POST /controls/validate and POST /control-templates/render are wired
to CONTROLS_CREATE rather than CONTROLS_READ. Both exercise the
authoring materialization path and exist to support the create / set-
data flow; a caller who cannot create controls has no use for the
result. Backwards-incompatible for OSS deployments that previously
called these routes with non-admin keys; deployments that want the
old behavior can override with
HeaderAuthProvider(operation_access={...}).

Storage namespace continues to come from get_namespace_key, matching
the bindings migration in #204. The unified principal-derived cutover
across /controls, /policies, /agents, and /evaluation is a follow-up.

Author: abhinav-galileo

sdks/typescript/src/generated/funcs/controls-get-schema.ts

@@ -27,6 +27,12 @@ import { Result } from "../types/fp.js";
  *
  * @remarks
  * Return the canonical JSON schema for ControlDefinition.
+ *
+ * Intentionally has no ``require_operation`` dependency: the schema is
+ * static metadata derived from the model class and exposes no tenant
+ * state. Routing it through the auth framework would force callers
+ * (and the upstream authorizer) to handle a meta-only operation that
+ * has no permission semantics.
  */
 export function controlsGetSchema(
   client: AgentControlSDKCore,

sdks/typescript/src/generated/funcs/controls-render-template.ts

@@ -31,6 +31,10 @@ import { Result } from "../types/fp.js";
  *
  * @remarks
  * Render a template-backed control without persisting it.
+ *
+ * Authorized as ``controls.create``: rendering is part of the authoring
+ * flow (the result feeds the create / update endpoints), so a caller
+ * who cannot create controls has no use for the materialized output.
  */
 export function controlsRenderTemplate(
   client: AgentControlSDKCore,

sdks/typescript/src/generated/funcs/controls-validate-data.ts

@@ -32,6 +32,11 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Validate control configuration data without saving it.
  *
+ * Authorized as ``controls.create`` rather than ``controls.read``:
+ * validation exercises the full create / update materialization path
+ * and exists to support authoring, so a caller who cannot create
+ * controls has no use for the result.
+ *
  * Args:
  *     request: Control configuration data to validate
  *     db: Database session (injected)

sdks/typescript/src/generated/sdk/controls.ts

@@ -25,6 +25,10 @@ export class Controls extends ClientSDK {
    *
    * @remarks
    * Render a template-backed control without persisting it.
+   *
+   * Authorized as ``controls.create``: rendering is part of the authoring
+   * flow (the result feeds the create / update endpoints), so a caller
+   * who cannot create controls has no use for the materialized output.
    */
   async renderTemplate(
     request: models.RenderControlTemplateRequest,
@@ -110,6 +114,12 @@ export class Controls extends ClientSDK {
    *
    * @remarks
    * Return the canonical JSON schema for ControlDefinition.
+   *
+   * Intentionally has no ``require_operation`` dependency: the schema is
+   * static metadata derived from the model class and exposes no tenant
+   * state. Routing it through the auth framework would force callers
+   * (and the upstream authorizer) to handle a meta-only operation that
+   * has no permission semantics.
    */
   async getSchema(
     options?: RequestOptions,
@@ -126,6 +136,11 @@ export class Controls extends ClientSDK {
    * @remarks
    * Validate control configuration data without saving it.
    *
+   * Authorized as ``controls.create`` rather than ``controls.read``:
+   * validation exercises the full create / update materialization path
+   * and exists to support authoring, so a caller who cannot create
+   * controls has no use for the result.
+   *
    * Args:
    *     request: Control configuration data to validate
    *     db: Database session (injected)

server/src/agent_control_server/endpoints/controls.py

@@ -33,7 +33,7 @@
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ..auth import require_admin_key
+from ..auth_framework import Operation, Principal, require_operation
 from ..db import get_async_db
 from ..errors import (
     APIValidationError,
@@ -446,8 +446,14 @@ async def _validate_control_definition(
 async def render_control_template(
     request: RenderControlTemplateRequest,
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_CREATE)),
 ) -> RenderControlTemplateResponse:
-    """Render a template-backed control without persisting it."""
+    """Render a template-backed control without persisting it.
+
+    Authorized as ``controls.create``: rendering is part of the authoring
+    flow (the result feeds the create / update endpoints), so a caller
+    who cannot create controls has no use for the materialized output.
+    """
     control_def = await _render_and_validate_template_input(
         TemplateControlInput(
             template=request.template,
@@ -461,13 +467,14 @@ async def render_control_template(
 
 @router.put(
     "",
-    dependencies=[Depends(require_admin_key)],
     response_model=CreateControlResponse,
     summary="Create a new control",
     response_description="Created control ID",
 )
 async def create_control(
-    request: CreateControlRequest, db: AsyncSession = Depends(get_async_db)
+    request: CreateControlRequest,
+    db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_CREATE)),
 ) -> CreateControlResponse:
     """
     Create a new control with a unique name.
@@ -550,7 +557,14 @@ async def create_control(
     response_description="JSON schema for ControlDefinition",
 )
 async def get_control_schema() -> GetControlSchemaResponse:
-    """Return the canonical JSON schema for ControlDefinition."""
+    """Return the canonical JSON schema for ControlDefinition.
+
+    Intentionally has no ``require_operation`` dependency: the schema is
+    static metadata derived from the model class and exposes no tenant
+    state. Routing it through the auth framework would force callers
+    (and the upstream authorizer) to handle a meta-only operation that
+    has no permission semantics.
+    """
     return GetControlSchemaResponse(
         schema=ControlDefinition.model_json_schema(by_alias=True)
     )
@@ -563,7 +577,9 @@ async def get_control_schema() -> GetControlSchemaResponse:
     response_description="Control metadata and configuration",
 )
 async def get_control(
-    control_id: int, db: AsyncSession = Depends(get_async_db)
+    control_id: int,
+    db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_READ)),
 ) -> GetControlResponse:
     """
     Retrieve a control by ID including its name and configuration data.
@@ -600,7 +616,9 @@ async def get_control(
     response_description="Control data payload",
 )
 async def get_control_data(
-    control_id: int, db: AsyncSession = Depends(get_async_db)
+    control_id: int,
+    db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_READ)),
 ) -> GetControlDataResponse:
     """
     Retrieve the configuration data for a control.
@@ -640,6 +658,7 @@ async def list_control_versions(
     ),
     limit: int = Query(_DEFAULT_PAGINATION_LIMIT, ge=1, le=_MAX_PAGINATION_LIMIT),
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_READ)),
 ) -> ListControlVersionsResponse:
     """List control versions ordered newest-first using cursor-based pagination."""
     page = await ControlService(db).list_versions(control_id, cursor=cursor, limit=limit)
@@ -673,6 +692,7 @@ async def get_control_version(
     control_id: int,
     version_num: int,
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_READ)),
 ) -> GetControlVersionResponse:
     """Return a specific control version, including its raw persisted snapshot."""
     version = await ControlService(db).get_version_or_404(control_id, version_num)
@@ -687,7 +707,6 @@ async def get_control_version(
 
 @router.put(
     "/{control_id}/data",
-    dependencies=[Depends(require_admin_key)],
     response_model=SetControlDataResponse,
     summary="Update control configuration data",
     response_description="Success confirmation",
@@ -696,6 +715,7 @@ async def set_control_data(
     control_id: int,
     request: SetControlDataRequest,
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_UPDATE)),
 ) -> SetControlDataResponse:
     """
     Update the configuration data for a control.
@@ -758,11 +778,18 @@ async def set_control_data(
     response_description="Validation result",
 )
 async def validate_control_data(
-    request: ValidateControlDataRequest, db: AsyncSession = Depends(get_async_db)
+    request: ValidateControlDataRequest,
+    db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_CREATE)),
 ) -> ValidateControlDataResponse:
     """
     Validate control configuration data without saving it.
 
+    Authorized as ``controls.create`` rather than ``controls.read``:
+    validation exercises the full create / update materialization path
+    and exists to support authoring, so a caller who cannot create
+    controls has no use for the result.
+
     Args:
         request: Control configuration data to validate
         db: Database session (injected)
@@ -798,6 +825,7 @@ async def list_controls(
     execution: str | None = Query(None, description="Filter by execution ('server' or 'sdk')"),
     tag: str | None = Query(None, description="Filter by tag"),
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_READ)),
 ) -> ListControlsResponse:
     """
     List all controls with optional filtering and cursor-based pagination.
@@ -884,7 +912,6 @@ async def list_controls(
 
 @router.delete(
     "/{control_id}",
-    dependencies=[Depends(require_admin_key)],
     response_model=DeleteControlResponse,
     summary="Delete a control",
     response_description="Deletion confirmation with dissociation info",
@@ -897,6 +924,7 @@ async def delete_control(
         "If false, fail if control is associated with any policy or agent.",
     ),
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_DELETE)),
 ) -> DeleteControlResponse:
     """
     Delete a control by ID.
@@ -1035,7 +1063,6 @@ async def delete_control(
 
 @router.patch(
     "/{control_id}",
-    dependencies=[Depends(require_admin_key)],
     response_model=PatchControlResponse,
     summary="Update control metadata",
     response_description="Updated control information",
@@ -1044,6 +1071,7 @@ async def patch_control(
     control_id: int,
     request: PatchControlRequest,
     db: AsyncSession = Depends(get_async_db),
+    _principal: Principal = Depends(require_operation(Operation.CONTROLS_UPDATE)),
 ) -> PatchControlResponse:
     """
     Update control metadata (name and/or enabled status).

server/src/agent_control_server/main.py

@@ -273,9 +273,15 @@ async def attach_version_header(request, call_next):  # type: ignore[no-untyped-
     dependencies=[Depends(require_api_key)],
 )
 app.include_router(
+    # ``/controls`` CRUD goes through the auth framework on each
+    # endpoint (``require_operation(Operation.CONTROLS_*)``); see the
+    # ``control_binding_router`` rationale below for the
+    # ``get_api_key_from_header`` mounting pattern. The single route on
+    # this router without ``require_operation`` is ``GET /controls/schema``,
+    # which is intentionally public meta — see its endpoint docstring.
     control_router,
     prefix=api_v1_prefix,
-    dependencies=[Depends(require_api_key)],
+    dependencies=[Depends(get_api_key_from_header)],
 )
 app.include_router(
     # The auth framework on each endpoint owns authentication and
@@ -300,9 +306,12 @@ async def attach_version_header(request, call_next):  # type: ignore[no-untyped-
     dependencies=[Depends(get_api_key_from_header)],
 )
 app.include_router(
+    # Control templates: ``/render`` is on the auth framework via
+    # ``require_operation(Operation.CONTROLS_CREATE)``; same mounting
+    # pattern as the controls and control-bindings routers.
     control_template_router,
     prefix=api_v1_prefix,
-    dependencies=[Depends(require_api_key)],
+    dependencies=[Depends(get_api_key_from_header)],
 )
 app.include_router(
     evaluation_router,