fix(server): authorize binding IDs with stored targets [SAO-17527]

Resolve caller identity before the namespace-scoped binding lookup, then authorize against the stored target. Preserve 401 responses and mask missing or target-denied bindings as 404.

Add provider and endpoint regression coverage and refresh generated TypeScript route descriptions.

Author: josjeon

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

@@ -28,15 +28,13 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Delete a control binding (namespace-wide)
+ * Delete a control binding
  *
  * @remarks
  * Delete a control binding by surrogate ID.
  *
- * See the GET-by-id docstring for the authorization scope: this route
- * is namespace-wide because the target identifiers are not available
- * before the binding is loaded. Use ``POST /by-key:delete`` for
- * target-scoped detach that includes the target in the request context.
+ * Authorization uses the binding's stored target identifiers. The deletion
+ * remains scoped to the namespace resolved by the authorizer.
  */
 export function controlBindingsDelete(
   client: AgentControlSDKCore,

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

@@ -28,17 +28,14 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Get a control binding (namespace-wide)
+ * Get a control binding
  *
  * @remarks
  * Read a single control binding by surrogate ID.
  *
- * Authorization is namespace-wide: the binding's target identifiers
- * are not available until after the row is loaded.
- * Callers whose authorization model requires per-target permissions
- * should use the natural-key endpoints (``PUT /by-key``,
- * ``POST /by-key:delete``) and the target-filtered list endpoint, all
- * of which include ``(target_type, target_id)`` in the request context.
+ * 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.
  */
 export function controlBindingsGet(
   client: AgentControlSDKCore,

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

@@ -28,15 +28,13 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Update a control binding (namespace-wide)
+ * Update a control binding
  *
  * @remarks
  * Update the ``enabled`` flag on a control binding.
  *
- * See the GET-by-id docstring for the authorization scope: this route
- * is namespace-wide because the target identifiers are not available
- * before the binding is loaded. Use ``PUT /by-key`` for target-scoped
- * upserts that include the target in the request context.
+ * Authorization uses the binding's stored target identifiers. The mutation
+ * remains scoped to the namespace resolved by the authorizer.
  */
 export function controlBindingsUpdate(
   client: AgentControlSDKCore,

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

@@ -118,15 +118,13 @@ export class ControlBindings extends ClientSDK {
   }
 
   /**
-   * Delete a control binding (namespace-wide)
+   * Delete a control binding
    *
    * @remarks
    * Delete a control binding by surrogate ID.
    *
-   * See the GET-by-id docstring for the authorization scope: this route
-   * is namespace-wide because the target identifiers are not available
-   * before the binding is loaded. Use ``POST /by-key:delete`` for
-   * target-scoped detach that includes the target in the request context.
+   * Authorization uses the binding's stored target identifiers. The deletion
+   * remains scoped to the namespace resolved by the authorizer.
    */
   async delete(
     request:
@@ -141,17 +139,14 @@ export class ControlBindings extends ClientSDK {
   }
 
   /**
-   * Get a control binding (namespace-wide)
+   * Get a control binding
    *
    * @remarks
    * Read a single control binding by surrogate ID.
    *
-   * Authorization is namespace-wide: the binding's target identifiers
-   * are not available until after the row is loaded.
-   * Callers whose authorization model requires per-target permissions
-   * should use the natural-key endpoints (``PUT /by-key``,
-   * ``POST /by-key:delete``) and the target-filtered list endpoint, all
-   * of which include ``(target_type, target_id)`` in the request context.
+   * 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.
    */
   async get(
     request:
@@ -166,15 +161,13 @@ export class ControlBindings extends ClientSDK {
   }
 
   /**
-   * Update a control binding (namespace-wide)
+   * Update a control binding
    *
    * @remarks
    * Update the ``enabled`` flag on a control binding.
    *
-   * See the GET-by-id docstring for the authorization scope: this route
-   * is namespace-wide because the target identifiers are not available
-   * before the binding is loaded. Use ``PUT /by-key`` for target-scoped
-   * upserts that include the target in the request context.
+   * Authorization uses the binding's stored target identifiers. The mutation
+   * remains scoped to the namespace resolved by the authorizer.
    */
   async update(
     request:

server/src/agent_control_server/auth_framework/config.py

@@ -53,6 +53,7 @@
 # Default flow.
 _MODE_ENV = "AGENT_CONTROL_AUTH_MODE"
 _UPSTREAM_URL_ENV = "AGENT_CONTROL_AUTH_UPSTREAM_URL"
+_UPSTREAM_IDENTITY_URL_ENV = "AGENT_CONTROL_AUTH_UPSTREAM_IDENTITY_URL"
 _UPSTREAM_TIMEOUT_ENV = "AGENT_CONTROL_AUTH_UPSTREAM_TIMEOUT_SECONDS"
 _UPSTREAM_TOKEN_ENV = "AGENT_CONTROL_AUTH_UPSTREAM_SERVICE_TOKEN"
 _UPSTREAM_TOKEN_HEADER_ENV = "AGENT_CONTROL_AUTH_UPSTREAM_SERVICE_TOKEN_HEADER"
@@ -110,7 +111,9 @@ 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``.
+      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.
 
     Runtime flow:
 
@@ -245,6 +248,7 @@ def _build_default_provider() -> RequestAuthorizer:
         try:
             upstream_config = HttpUpstreamConfig(
                 url=url,
+                identity_url=(os.environ.get(_UPSTREAM_IDENTITY_URL_ENV) or "").strip() or None,
                 timeout_seconds=timeout,
                 service_token=token,
                 service_token_header=token_header,

server/src/agent_control_server/auth_framework/core.py

@@ -26,7 +26,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from enum import StrEnum
-from typing import Any, Protocol
+from typing import Any, Protocol, runtime_checkable
 
 from fastapi import Request
 
@@ -115,6 +115,17 @@ async def authorize(
     ) -> Principal: ...
 
 
+@runtime_checkable
+class IdentityResolver(Protocol):
+    """Optional 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.
+    """
+
+    async def resolve_identity(self, request: Request, operation: Operation) -> Principal: ...
+
+
 _default_authorizer: RequestAuthorizer | None = None
 _operation_authorizers: dict[Operation, RequestAuthorizer] = {}
 

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

@@ -75,6 +75,10 @@ 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

@@ -46,6 +46,7 @@
 from datetime import datetime
 from time import perf_counter
 from typing import Any
+from urllib.parse import urlsplit, urlunsplit
 
 import httpx
 from agent_control_models.errors import ErrorCode, ErrorReason
@@ -67,6 +68,9 @@
 _logger = get_logger(__name__)
 
 _DEFAULT_FORWARDED_HEADERS = ("X-API-Key", "Authorization", "Cookie")
+_ORBIT_MANAGEMENT_PATH = "/internal/auth/agent_control/check_management_access"
+_ORBIT_IDENTITY_PATH = "/internal/auth/resolve_tenant_context"
+_IDENTITY_OPERATION = "identity.resolve"
 
 _AUTH_UPSTREAM_ATTEMPTS = Counter(
     "agent_control_server_auth_upstream_attempts_total",
@@ -180,6 +184,10 @@ class HttpUpstreamConfig:
     max_keepalive_connections: int = 20
     """Maximum idle connections retained for the auth upstream."""
 
+    identity_url: str | None = None
+    """URL for credential and namespace resolution. If omitted, the Orbit
+    identity URL is derived from the known management authorization path."""
+
     def __post_init__(self) -> None:
         if self.keepalive_expiry_seconds < 0:
             raise ValueError("keepalive_expiry_seconds must be greater than or equal to 0")
@@ -213,6 +221,7 @@ def __init__(
         client: httpx.AsyncClient | None = None,
     ) -> None:
         self._config = config
+        self._identity_url = config.identity_url or _derive_orbit_identity_url(config.url)
         self._owns_client = client is None
         if client is not None:
             self._client = client
@@ -245,19 +254,49 @@ async def authorize(
         if context:
             payload["context"] = context
 
-        response = await self._post_upstream(operation, payload, headers)
-        return self._handle_response(response, operation, context)
+        response = await self._post_upstream(operation.value, payload, headers)
+        return self._handle_response(response, operation.value, context)
+
+    async def resolve_identity(self, request: Request, operation: Operation) -> Principal:
+        """Authenticate with the upstream before a namespace-scoped lookup."""
+        del operation  # Target-specific permission is checked by authorize afterward.
+        if self._identity_url is None:
+            raise APIError(
+                status_code=500,
+                error_code=ErrorCode.AUTH_MISCONFIGURED,
+                reason=ErrorReason.INTERNAL_ERROR,
+                detail="Authorization identity endpoint is not configured.",
+                hint="Set AGENT_CONTROL_AUTH_UPSTREAM_IDENTITY_URL.",
+            )
+        response = await self._post_upstream(
+            _IDENTITY_OPERATION,
+            None,
+            self._forward_headers(request),
+            url=self._identity_url,
+        )
+        if response.status_code == 404:
+            raise APIError(
+                status_code=502,
+                error_code=ErrorCode.AUTH_UPSTREAM_REJECTED,
+                reason=ErrorReason.INTERNAL_ERROR,
+                detail="Authorization identity endpoint was not found.",
+                hint="Check the configured authorization identity URL.",
+            )
+        principal = self._handle_response(response, _IDENTITY_OPERATION, None)
+        return Principal(namespace_key=principal.namespace_key, caller_id=principal.caller_id)
 
     async def _post_upstream(
         self,
-        operation: Operation,
-        payload: dict[str, Any],
+        operation: str,
+        payload: dict[str, Any] | None,
         headers: dict[str, str],
+        *,
+        url: str | None = None,
     ) -> httpx.Response:
         started = perf_counter()
         try:
             response = await self._client.post(
-                self._config.url,
+                url or self._config.url,
                 json=payload,
                 headers=headers,
             )
@@ -270,7 +309,7 @@ async def _post_upstream(
             )
             _logger.warning(
                 "Auth upstream unreachable for operation %s: %s",
-                operation.value,
+                operation,
                 exc,
             )
             raise _authorization_service_unavailable_error() from exc
@@ -301,7 +340,7 @@ def _forward_headers(self, request: Request) -> dict[str, str]:
     def _handle_response(
         self,
         response: httpx.Response,
-        operation: Operation,
+        operation: str,
         context: dict[str, Any] | None,
     ) -> Principal:
         status = response.status_code
@@ -318,7 +357,7 @@ def _handle_response(
         if status == 403:
             raise ForbiddenError(
                 error_code=ErrorCode.AUTH_INSUFFICIENT_PRIVILEGES,
-                detail=f"Not authorized to perform {operation.value!r}.",
+                detail=f"Not authorized to perform {operation!r}.",
                 hint="Contact your administrator if you expected access.",
             )
         if status == 404:
@@ -343,7 +382,7 @@ def _handle_response(
                 hint = f"{hint} Retry-After: {retry_after}."
             _logger.warning(
                 "Upstream returned 429 for operation %s",
-                operation.value,
+                operation,
             )
             raise APIError(
                 status_code=503,
@@ -355,7 +394,7 @@ def _handle_response(
         if 400 <= status < 500:
             _logger.warning(
                 "Authorization upstream rejected operation %s with status %d",
-                operation.value,
+                operation,
                 status,
             )
             raise APIError(
@@ -375,7 +414,7 @@ def _handle_response(
         _logger.warning(
             "Unexpected upstream status %d for operation %s",
             status,
-            operation.value,
+            operation,
         )
         raise APIError(
             status_code=503,
@@ -420,21 +459,21 @@ def _parse_principal(self, response: httpx.Response) -> Principal:
 
 
 def _observe_upstream_attempt(
-    operation: Operation,
+    operation: str,
     duration_seconds: float,
     *,
     outcome: str,
     status_code: int | None = None,
     error: httpx.HTTPError | None = None,
 ) -> None:
     _AUTH_UPSTREAM_ATTEMPTS.labels(
-        operation=operation.value,
+        operation=operation,
         outcome=outcome,
         status_code=str(status_code) if status_code is not None else "none",
         error_type=type(error).__name__ if error is not None else "none",
     ).inc()
     _AUTH_UPSTREAM_ATTEMPT_DURATION.labels(
-        operation=operation.value,
+        operation=operation,
         outcome=outcome,
     ).observe(duration_seconds)
 
@@ -449,6 +488,17 @@ def _authorization_service_unavailable_error() -> APIError:
     )
 
 
+def _derive_orbit_identity_url(url: str) -> str | None:
+    """Resolve Orbit's existing identity route from its management route."""
+    parts = urlsplit(url)
+    if not parts.path.endswith(_ORBIT_MANAGEMENT_PATH):
+        return None
+    prefix = parts.path[: -len(_ORBIT_MANAGEMENT_PATH)]
+    return urlunsplit(
+        (parts.scheme, parts.netloc, prefix + _ORBIT_IDENTITY_PATH, parts.query, parts.fragment)
+    )
+
+
 def _ensure_target_context_matches_grant(
     context: dict[str, Any] | None,
     principal: Principal,