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,15 @@ async def _validate_control_definition(
     summary="Render a control template preview",
     response_description="Rendered control preview",
 )
+# Authorized as CONTROLS_CREATE: render is part of the create flow
+# (its output feeds the create / set-data endpoints); a caller who
+# cannot create controls has no use for the materialized output.
 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 +554,13 @@ async def create_control(
     summary="Get control definition JSON schema",
     response_description="JSON schema for ControlDefinition",
 )
+# Public schema metadata: intentionally has no ``require_operation``
+# dependency. The response is static, derived from the model class, and
+# exposes no tenant state. Mounting it under the framework would force
+# every authorizer to handle a meta-only operation with no permission
+# semantics.
 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 +773,9 @@ async def set_control_data(
     summary="Validate control configuration",
     response_description="Validation result",
 )
+# Authorized as CONTROLS_CREATE rather than CONTROLS_READ: validate
+# exercises the same materialization path as create / set-data and is
+# only useful to a caller who can act on the result.
 async def validate_control_data(
     request: ValidateControlDataRequest,
     db: AsyncSession = Depends(get_async_db),
@@ -785,11 +784,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

@@ -278,7 +278,8 @@ async def attach_version_header(request, call_next):  # type: ignore[no-untyped-
     # ``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.
+    # which is intentionally public meta — see the comment above its
+    # handler in ``endpoints/controls.py``.
     control_router,
     prefix=api_v1_prefix,
     dependencies=[Depends(get_api_key_from_header)],

server/tests/test_controls_auth.py

@@ -338,28 +338,3 @@ def test_no_auth_mode_allows_writes_without_credentials(
     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")