feat(auth): make the runtime-token header configurable

Let the runtime-token JWT verifier read its token from a configurable
request header (env AGENT_CONTROL_RUNTIME_TOKEN_HEADER), defaulting to
Authorization so existing deployments are unaffected.

Why: when Agent Control runs behind an API gateway that reserves the
Authorization header for its own downstream identity JWT, the gateway
overwrites the runtime token on the hot evaluation path and the verifier
fails. Pointing the verifier at a dedicated header (e.g.
X-Agent-Control-Runtime-Token) lets the two tokens coexist.

- LocalJwtVerifyProvider gains a header_name param. On Authorization the
  Bearer scheme prefix stays required (back-compat); on a dedicated header
  the raw token is accepted (Bearer optional). The token is still
  signature-verified, scope-checked, and target-bound after extraction, so
  the header choice cannot bypass verification.
- config.py resolves the header via _resolve_runtime_token_header();
  a whitespace-only env value falls back to the default.
- Tests: custom-header raw/Bearer acceptance, case-insensitive lookup,
  no fallback to Authorization, whitespace/blank handling, and app-level
  E2E through /api/v1/evaluation (gateway JWT on Authorization coexists
  with the runtime token on a dedicated header).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: jjeonsplunk

server/src/agent_control_server/auth_framework/config.py

@@ -21,6 +21,10 @@
   The ``runtime.token_exchange`` operation continues to flow through
   the default authorizer because the exchange itself is shaped like a
   management call (forward credential, get grant).
+  ``AGENT_CONTROL_RUNTIME_TOKEN_HEADER`` (default ``Authorization``)
+  selects which request header the ``jwt`` verifier reads the runtime
+  token from, so the server can run behind a gateway that reserves
+  ``Authorization`` for its own downstream identity JWT.
 """
 
 from __future__ import annotations
@@ -39,6 +43,7 @@
     NoAuthProvider,
 )
 from .providers.http_upstream import HttpUpstreamConfig
+from .providers.local_jwt import DEFAULT_RUNTIME_TOKEN_HEADER
 
 _logger = get_logger(__name__)
 
@@ -60,6 +65,7 @@
 _RUNTIME_MODE_ENV = "AGENT_CONTROL_RUNTIME_AUTH_MODE"
 _RUNTIME_TOKEN_SECRET_ENV = "AGENT_CONTROL_RUNTIME_TOKEN_SECRET"
 _RUNTIME_TOKEN_TTL_ENV = "AGENT_CONTROL_RUNTIME_TOKEN_TTL_SECONDS"
+_RUNTIME_TOKEN_HEADER_ENV = "AGENT_CONTROL_RUNTIME_TOKEN_HEADER"
 _DEFAULT_RUNTIME_TOKEN_TTL_SECONDS = 300
 # HS256 needs at least 256 bits (32 bytes) of secret material to be safe
 # against brute force; reject anything shorter so production deployments
@@ -378,12 +384,30 @@ def _build_runtime_provider(
     if mode == "jwt":
         if config is None:
             raise RuntimeError(f"{_RUNTIME_MODE_ENV}=jwt but runtime auth config is missing.")
-        return LocalJwtVerifyProvider(secret=config.secret)
+        return LocalJwtVerifyProvider(
+            secret=config.secret,
+            header_name=_resolve_runtime_token_header(),
+        )
     raise RuntimeError(
         f"Unknown runtime auth mode {mode!r}; expected 'none', 'api_key', or 'jwt'."
     )
 
 
+def _resolve_runtime_token_header() -> str:
+    """Return the header the runtime JWT verifier reads the Bearer token from.
+
+    Defaults to ``Authorization``. Deployments behind a gateway that
+    overwrites ``Authorization`` with its own downstream identity JWT can
+    point the verifier at a dedicated header (e.g.
+    ``X-Agent-Control-Runtime-Token``) so the two tokens no longer
+    collide on the hot evaluation path.
+    """
+    raw = os.environ.get(_RUNTIME_TOKEN_HEADER_ENV)
+    if raw is None or not raw.strip():
+        return DEFAULT_RUNTIME_TOKEN_HEADER
+    return raw.strip()
+
+
 def _load_runtime_auth_config(*, require_secret: bool = False) -> RuntimeAuthConfig | None:
     """Parse, validate, and return the runtime-auth config from env.
 

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

@@ -1,11 +1,17 @@
 """Authorizer that verifies a locally-minted runtime token.
 
-Wired to the runtime resolution path. Reads a Bearer token from the
-``Authorization`` header, verifies the signature against the runtime
-secret, checks the token's scope covers the requested operation, and
-returns a :class:`Principal` carrying the bound target. When a
-``context_builder`` on the dependency must surface matching
-``target_type`` / ``target_id`` values for target-bound tokens.
+Wired to the runtime resolution path. Reads a Bearer token from a
+configurable header (``Authorization`` by default), verifies the
+signature against the runtime secret, checks the token's scope covers
+the requested operation, and returns a :class:`Principal` carrying the
+bound target. When a ``context_builder`` on the dependency must surface
+matching ``target_type`` / ``target_id`` values for target-bound tokens.
+
+The header the runtime token arrives on is configurable so the server
+can sit behind a gateway that reserves ``Authorization`` for its own
+downstream identity JWT. When the token rides a dedicated header (e.g.
+``X-Agent-Control-Runtime-Token``), the ``Bearer`` scheme prefix is
+optional; on ``Authorization`` it stays required for back-compat.
 """
 
 from __future__ import annotations
@@ -19,14 +25,28 @@
 from ..core import Operation, Principal, RequestAuthorizer
 from ..runtime_token import RuntimeTokenError, verify_runtime_token
 
+DEFAULT_RUNTIME_TOKEN_HEADER = "Authorization"
+
 
 class LocalJwtVerifyProvider(RequestAuthorizer):
     """Verifies a runtime Bearer token and emits a target-bound :class:`Principal`."""
 
-    def __init__(self, *, secret: str) -> None:
+    def __init__(
+        self,
+        *,
+        secret: str,
+        header_name: str = DEFAULT_RUNTIME_TOKEN_HEADER,
+    ) -> None:
         if not secret:
             raise ValueError("LocalJwtVerifyProvider requires a non-empty secret.")
+        if not header_name or not header_name.strip():
+            raise ValueError("LocalJwtVerifyProvider requires a non-empty header_name.")
         self._secret = secret
+        self._header_name = header_name.strip()
+        # The Bearer scheme is mandatory on Authorization (existing SDK
+        # contract) but optional on a dedicated runtime-token header,
+        # where the raw token is the whole value.
+        self._require_bearer = self._header_name.lower() == "authorization"
 
     async def authorize(
         self,
@@ -79,18 +99,29 @@ async def authorize(
         )
 
     def _extract_bearer_token(self, request: Request) -> str:
-        header = request.headers.get("Authorization")
+        header = request.headers.get(self._header_name)
         if not header:
             raise AuthenticationError(
                 error_code=ErrorCode.AUTH_MISSING_KEY,
-                detail="Missing Authorization header.",
+                detail=f"Missing {self._header_name} header.",
                 hint="Present a Bearer runtime token.",
             )
-        scheme, _, value = header.partition(" ")
-        if scheme.lower() != "bearer" or not value:
+        scheme, sep, value = header.partition(" ")
+        if sep and scheme.lower() == "bearer":
+            token = value.strip()
+        elif self._require_bearer:
             raise AuthenticationError(
                 error_code=ErrorCode.AUTH_MISSING_KEY,
-                detail="Authorization header must be a Bearer token.",
-                hint="Format: ``Authorization: Bearer <token>``.",
+                detail=f"{self._header_name} header must be a Bearer token.",
+                hint=f"Format: ``{self._header_name}: Bearer <token>``.",
+            )
+        else:
+            # Dedicated runtime-token header: accept the raw token.
+            token = header.strip()
+        if not token:
+            raise AuthenticationError(
+                error_code=ErrorCode.AUTH_MISSING_KEY,
+                detail=f"{self._header_name} header is empty.",
+                hint="Present a Bearer runtime token.",
             )
-        return value.strip()
+        return token