fix(server): preserve legacy binding ID authorization

Author: josjeon

sdks/typescript/src/generated/funcs/control-bindings-delete.ts

@@ -33,8 +33,9 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Delete a control binding by surrogate ID.
  *
- * Authorization uses the binding's stored target identifiers. The deletion
- * remains scoped to the namespace resolved by the authorizer.
+ * Target-aware authorizers use the binding's stored target identifiers.
+ * Other authorizers retain namespace-wide authorization. The deletion
+ * remains scoped to the authorized namespace.
  */
 export function controlBindingsDelete(
   client: AgentControlSDKCore,

sdks/typescript/src/generated/funcs/control-bindings-get.ts

@@ -33,9 +33,9 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Read a single control binding by surrogate ID.
  *
- * Authorization uses the binding's stored target identifiers. After
- * authorization succeeds, the row is loaded again using the namespace
- * resolved by the authorizer before any binding data is returned.
+ * Target-aware authorizers use the binding's stored target identifiers.
+ * Other authorizers retain namespace-wide authorization. The row is loaded
+ * using the authorized namespace before any binding data is returned.
  */
 export function controlBindingsGet(
   client: AgentControlSDKCore,

sdks/typescript/src/generated/funcs/control-bindings-update.ts

@@ -33,8 +33,9 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Update the ``enabled`` flag on a control binding.
  *
- * Authorization uses the binding's stored target identifiers. The mutation
- * remains scoped to the namespace resolved by the authorizer.
+ * Target-aware authorizers use the binding's stored target identifiers.
+ * Other authorizers retain namespace-wide authorization. The mutation
+ * remains scoped to the authorized namespace.
  */
 export function controlBindingsUpdate(
   client: AgentControlSDKCore,

sdks/typescript/src/generated/sdk/control-bindings.ts

@@ -123,8 +123,9 @@ export class ControlBindings extends ClientSDK {
    * @remarks
    * Delete a control binding by surrogate ID.
    *
-   * Authorization uses the binding's stored target identifiers. The deletion
-   * remains scoped to the namespace resolved by the authorizer.
+   * Target-aware authorizers use the binding's stored target identifiers.
+   * Other authorizers retain namespace-wide authorization. The deletion
+   * remains scoped to the authorized namespace.
    */
   async delete(
     request:
@@ -144,9 +145,9 @@ export class ControlBindings extends ClientSDK {
    * @remarks
    * Read a single control binding by surrogate ID.
    *
-   * Authorization uses the binding's stored target identifiers. After
-   * authorization succeeds, the row is loaded again using the namespace
-   * resolved by the authorizer before any binding data is returned.
+   * Target-aware authorizers use the binding's stored target identifiers.
+   * Other authorizers retain namespace-wide authorization. The row is loaded
+   * using the authorized namespace before any binding data is returned.
    */
   async get(
     request:
@@ -166,8 +167,9 @@ export class ControlBindings extends ClientSDK {
    * @remarks
    * Update the ``enabled`` flag on a control binding.
    *
-   * Authorization uses the binding's stored target identifiers. The mutation
-   * remains scoped to the namespace resolved by the authorizer.
+   * Target-aware authorizers use the binding's stored target identifiers.
+   * Other authorizers retain namespace-wide authorization. The mutation
+   * remains scoped to the authorized namespace.
    */
   async update(
     request:

server/src/agent_control_server/auth_framework/config.py

@@ -111,9 +111,10 @@ def configure_auth_from_env() -> None:
       is unset, startup selects ``api_key`` only if local API-key validation is
       enabled; otherwise it selects ``none``.
     - ``AGENT_CONTROL_AUTH_MODE=http_upstream``: :class:`HttpUpstreamAuthProvider`
-      pointed at ``AGENT_CONTROL_AUTH_UPSTREAM_URL``. By-ID binding routes also
-      use ``AGENT_CONTROL_AUTH_UPSTREAM_IDENTITY_URL`` when the identity URL
-      cannot be derived from Orbit's management authorization URL.
+      pointed at ``AGENT_CONTROL_AUTH_UPSTREAM_URL``. By-ID binding routes use
+      stored-target authorization when an identity URL can be derived from
+      Orbit's management URL or ``AGENT_CONTROL_AUTH_UPSTREAM_IDENTITY_URL`` is
+      set. Other upstreams retain the prior namespace-wide authorization flow.
 
     Runtime flow:
 

server/src/agent_control_server/auth_framework/core.py

@@ -117,12 +117,17 @@ async def authorize(
 
 @runtime_checkable
 class IdentityResolver(Protocol):
-    """Optional credential and namespace lookup for target-bound authorizers.
+    """Opt-in credential and namespace lookup for target-bound authorizers.
 
-    It does not grant resource access. The route still calls ``authorize``
-    with the stored target after the namespace-scoped lookup.
+    Providers opt in only when they can resolve an identity without changing
+    the authorization behavior of existing namespace-wide binding ID routes.
+    The route then calls ``authorize`` with the stored target after the
+    namespace-scoped lookup.
     """
 
+    @property
+    def binding_target_authorization(self) -> bool: ...
+
     async def resolve_identity(self, request: Request, operation: Operation) -> Principal: ...
 
 

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

@@ -75,10 +75,6 @@ def __init__(
         )
         self._default_namespace_key = default_namespace_key
 
-    async def resolve_identity(self, request: Request, operation: Operation) -> Principal:
-        """Apply the local operation gate before a namespace-scoped lookup."""
-        return await self.authorize(request, operation)
-
     async def authorize(
         self,
         request: Request,

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

@@ -238,6 +238,11 @@ def __init__(
                 client_kwargs["verify"] = ssl.create_default_context(cafile=config.ca_file)
             self._client = httpx.AsyncClient(**client_kwargs)
 
+    @property
+    def binding_target_authorization(self) -> bool:
+        """Use stored-target checks only when a separate identity URL exists."""
+        return self._identity_url is not None
+
     async def aclose(self) -> None:
         """Release the HTTP client if this provider created it."""
         if self._owns_client:

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

@@ -53,6 +53,8 @@ def validate_http_field_name(name: str) -> str:
 class LocalJwtVerifyProvider(RequestAuthorizer):
     """Verifies a runtime Bearer token and emits a target-bound :class:`Principal`."""
 
+    binding_target_authorization = True
+
     def __init__(
         self,
         *,

server/src/agent_control_server/endpoints/control_bindings.py

@@ -77,16 +77,20 @@ async def _binding_list_context(request: Request) -> dict[str, Any]:
 def _require_binding_operation(
     operation: Operation,
 ) -> Callable[..., Awaitable[Principal]]:
-    """Authorize a by-ID route against the binding's stored target."""
+    """Use stored-target authorization when the provider opts in."""
 
     async def dependency(request: Request, binding_id: int) -> Principal:
         authorizer = get_authorizer(operation)
-        if isinstance(authorizer, IdentityResolver):
-            identity = await authorizer.resolve_identity(request, operation)
-        else:
-            # Legacy providers can still resolve namespace-wide operations.
-            # Target-bound providers should implement IdentityResolver.
-            identity = await authorizer.authorize(request, operation)
+        if (
+            not isinstance(authorizer, IdentityResolver)
+            or not authorizer.binding_target_authorization
+        ):
+            # Preserve the existing single namespace-wide authorization call
+            # for providers without an independent identity lookup. Their
+            # operation contract may reject a new target context altogether.
+            return await authorizer.authorize(request, operation)
+
+        identity = await authorizer.resolve_identity(request, operation)
         # Use a short-lived session so no database connection is held while the
         # authorization provider performs a potentially remote request.
         async with AsyncSessionLocal() as db:
@@ -236,9 +240,9 @@ async def get_control_binding(
 ) -> GetControlBindingResponse:
     """Read a single control binding by surrogate ID.
 
-    Authorization uses the binding's stored target identifiers. After
-    authorization succeeds, the row is loaded again using the namespace
-    resolved by the authorizer before any binding data is returned.
+    Target-aware authorizers use the binding's stored target identifiers.
+    Other authorizers retain namespace-wide authorization. The row is loaded
+    using the authorized namespace before any binding data is returned.
     """
     service = ControlBindingsService(db)
     binding = await service.get_binding_or_404(
@@ -295,8 +299,9 @@ async def patch_control_binding(
 ) -> PatchControlBindingResponse:
     """Update the ``enabled`` flag on a control binding.
 
-    Authorization uses the binding's stored target identifiers. The mutation
-    remains scoped to the namespace resolved by the authorizer.
+    Target-aware authorizers use the binding's stored target identifiers.
+    Other authorizers retain namespace-wide authorization. The mutation
+    remains scoped to the authorized namespace.
     """
     service = ControlBindingsService(db)
     binding = await service.set_enabled(
@@ -321,8 +326,9 @@ async def delete_control_binding(
 ) -> DeleteControlBindingResponse:
     """Delete a control binding by surrogate ID.
 
-    Authorization uses the binding's stored target identifiers. The deletion
-    remains scoped to the namespace resolved by the authorizer.
+    Target-aware authorizers use the binding's stored target identifiers.
+    Other authorizers retain namespace-wide authorization. The deletion
+    remains scoped to the authorized namespace.
     """
     service = ControlBindingsService(db)
     await service.delete_binding(namespace_key=principal.namespace_key, binding_id=binding_id)