fix(server): keep public docstrings API-level on migrated controls routes

Move auth-framework rationale on /controls/schema, /controls/validate,
and /control-templates/render from route docstrings into normal code
comments. The docstrings flow into the generated TypeScript SDK as
public API documentation, so internal terminology like
``require_operation`` and "upstream authorizer" should not appear
there. Function-level comments preserve the rationale for readers of
the source.

Also remove the skipped placeholder test for the project-scoped
credential deny scenario; that scenario depends on a deployment-side
provider configuration that is not part of the OSS server, so
tracking it as a permanent skipped test in this repo was the wrong
home for it.

Regenerate the TypeScript SDK to drop the leaked rationale lines.

Author: abhinav-galileo

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

@@ -27,12 +27,6 @@ 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,10 +31,6 @@ 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,11 +32,6 @@ 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,10 +25,6 @@ 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,
@@ -114,12 +110,6 @@ 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,
@@ -136,11 +126,6 @@ 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

@@ -443,17 +443,13 @@ async def _validate_control_definition(
     summary="Render a control template preview",
     response_description="Rendered control preview",
 )
+# Rendering is part of the authoring flow, so require create access.
 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.
-
-    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.
-    """
+    """Render a template-backed control without persisting it."""
     control_def = await _render_and_validate_template_input(
         TemplateControlInput(
             template=request.template,
@@ -556,15 +552,9 @@ async def create_control(
     summary="Get control definition JSON schema",
     response_description="JSON schema for ControlDefinition",
 )
+# Public schema metadata: no tenant state, no auth operation.
 async def get_control_schema() -> GetControlSchemaResponse:
-    """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 the canonical JSON schema for ControlDefinition."""
     return GetControlSchemaResponse(
         schema=ControlDefinition.model_json_schema(by_alias=True)
     )
@@ -777,6 +767,7 @@ async def set_control_data(
     summary="Validate control configuration",
     response_description="Validation result",
 )
+# Validation uses the authoring path, so require create access.
 async def validate_control_data(
     request: ValidateControlDataRequest,
     db: AsyncSession = Depends(get_async_db),
@@ -785,11 +776,6 @@ async def validate_control_data(
     """
     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/main.py

@@ -273,12 +273,7 @@ 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.
+    # Endpoint dependencies handle auth; this advertises X-API-Key.
     control_router,
     prefix=api_v1_prefix,
     dependencies=[Depends(get_api_key_from_header)],
@@ -306,9 +301,7 @@ 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.
+    # Endpoint dependencies handle auth; this advertises X-API-Key.
     control_template_router,
     prefix=api_v1_prefix,
     dependencies=[Depends(get_api_key_from_header)],

server/tests/test_controls_auth.py

@@ -1,19 +1,4 @@
-"""HTTP-level coverage for the auth seam on ``/controls`` and
-``/control-templates``.
-
-These tests exercise the wiring of ``require_operation`` on each route
-through the default ``HeaderAuthProvider``: read operations require any
-valid credential (``CONTROLS_READ`` -> ``AUTHENTICATED``), write
-operations require an admin credential
-(``CONTROLS_CREATE`` / ``CONTROLS_UPDATE`` / ``CONTROLS_DELETE`` ->
-``ADMIN``), and ``GET /controls/schema`` is intentionally outside the
-framework so it stays publicly reachable.
-
-The provider primitives themselves are exercised in
-``tests/test_auth_framework.py``; this file focuses on each endpoint
-calling the right ``Operation`` so a future change to the operation
-mapping is caught at the route level.
-"""
+"""HTTP-level auth coverage for ``/controls`` and ``/control-templates``."""
 
 from __future__ import annotations
 
@@ -42,7 +27,7 @@ def _create_control(client: TestClient, name: str | None = None) -> int:
 
 
 # ---------------------------------------------------------------------------
-# /controls/schema is intentionally public meta — no require_operation.
+# /controls/schema is intentionally public metadata.
 # ---------------------------------------------------------------------------
 
 
@@ -165,7 +150,7 @@ def test_non_admin_cannot_create_control(non_admin_client: TestClient) -> None:
         },
     )
 
-    # Then: the request is forbidden by the auth seam
+    # Then: the request is forbidden
     assert resp.status_code == 403, resp.text
 
 
@@ -217,12 +202,7 @@ def test_non_admin_cannot_delete_control(
 def test_non_admin_cannot_validate_control_data(
     non_admin_client: TestClient,
 ) -> None:
-    """``/controls/validate`` is wired to ``CONTROLS_CREATE`` rather than
-    ``CONTROLS_READ`` because validation exercises the create / update
-    materialization path; a caller who cannot create has no use for the
-    result. This pins that decision so it can't drift to ``READ``
-    accidentally.
-    """
+    """``/controls/validate`` requires ``CONTROLS_CREATE``."""
     # When: a non-admin attempts to validate a draft payload
     resp = non_admin_client.post(
         f"{_CONTROLS_URL}/validate",
@@ -234,19 +214,14 @@ def test_non_admin_cannot_validate_control_data(
 
 
 def test_non_admin_cannot_render_template(non_admin_client: TestClient) -> None:
-    """``/control-templates/render`` is wired to ``CONTROLS_CREATE`` for
-    the same reason as ``/validate``: rendering is part of the authoring
-    flow. The 422 path is not exercised here — only the auth gate is
-    asserted, so the request shape need not validate.
-    """
+    """``/control-templates/render`` requires ``CONTROLS_CREATE``."""
     # When: a non-admin attempts to render a template
     resp = non_admin_client.post(
         f"{_TEMPLATES_URL}/render",
         json={"template": {}, "template_values": {}},
     )
 
-    # Then: rendering is admin-only — the auth gate fires before body
-    # validation reaches the materialization path
+    # Then: rendering is admin-only
     assert resp.status_code == 403, resp.text
 
 
@@ -337,29 +312,3 @@ def test_no_auth_mode_allows_writes_without_credentials(
     assert resp.status_code == 200, resp.text
     assert "control_id" in resp.json()
 
-
-# ---------------------------------------------------------------------------
-# Project-scoped API key deny — pending header forwarding follow-up.
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.skip(
-    reason=(
-        "Requires the upstream auth provider to forward an additional "
-        "configurable credential header. The default forward set is "
-        "fixed to (X-API-Key, Authorization, Cookie); deployments that "
-        "use a different credential header can't surface a "
-        "project-scoped credential to upstream until that becomes "
-        "configurable. Re-enable when the follow-up PR adds an "
-        "operator-configurable extra forward list."
-    )
-)
-def test_project_scoped_credential_denied_on_org_scoped_controls() -> None:
-    """Stub for the deny-test promised by the upstream provider's
-    response contract: a project-scoped credential calling an
-    org-scoped operation (``controls.*``) should resolve to a 403 from
-    the upstream. The end-to-end path is unreachable today because the
-    provider's credential-forward list is not configurable; tracked as
-    the next follow-up after this PR.
-    """
-    pytest.fail("test stub — see skip reason")