feat(server): pluggable request-auth framework (management + runtime)

[abhinav-galileo]

Summary

Pluggable request-auth framework that handles both auth flows the system needs:

• Management. Online check on every request. The default authorizer authenticates the credential and authorizes the operation; on production this is HttpUpstreamAuthProvider forwarding to a configurable upstream service.
• Runtime. Two-phase exchange-then-verify. A target-bearing call presents a long-lived credential plus (target_type, target_id) to a token exchange endpoint; the server mints a short-lived HS256 JWT bound to that target. Subsequent runtime calls verify the JWT locally — no upstream round-trip on the hot path.

Both flows route through the same primitives (Operation vocabulary on endpoints, Principal returned, RequestAuthorizer Protocol installed); a per-operation registry lets a deployment point management ops at one provider and runtime ops at another.

Migrates the /control-bindings endpoint family onto the framework and ships the runtime token exchange endpoint. The runtime resolution path itself (/evaluation etc.) is wired in a follow-up — its provider override (LocalJwtVerifyProvider) is already in place when the runtime secret is configured.

Module layout

server/src/agent_control_server/auth_framework/
  __init__.py                   # public API
  core.py                       # Operation, Principal, RequestAuthorizer, require_operation, registry
  config.py                     # configure_auth_from_env (env-driven setup, both flows)
  runtime_token.py              # HS256 mint / verify helpers
  providers/
    __init__.py
    header.py                   # HeaderAuthProvider + DEFAULT_OPERATION_ACCESS
    http_upstream.py            # HttpUpstreamAuthProvider (forward + parse grant)
    local_jwt.py                # LocalJwtVerifyProvider (hot-path JWT verify)

server/src/agent_control_server/endpoints/
  auth.py                       # POST /api/v1/auth/runtime-token-exchange

auth.py (legacy local credential check) is unchanged; HeaderAuthProvider re-uses _validate_api_key from it. Non-binding routes still go through the legacy router-level gate; their migration happens in follow-up PRs.

Operation vocabulary

class Operation(StrEnum):
    # Wired on endpoints in this PR.
    CONTROL_BINDINGS_READ = "control_bindings.read"
    CONTROL_BINDINGS_WRITE = "control_bindings.write"
    RUNTIME_TOKEN_EXCHANGE = "runtime.token_exchange"

    # Reserved; not yet wired on endpoints.
    CONTROLS_READ = "controls.read"
    CONTROLS_CREATE = "controls.create"
    CONTROLS_UPDATE = "controls.update"
    CONTROLS_DELETE = "controls.delete"
    RUNTIME_USE = "runtime.use"

Per-operation authorizer registry

set_authorizer(authorizer, operation=...) overrides the default for one operation. Without operation=, it becomes the default for every operation that does not have a specific binding. Used to route management ops through one provider and Operation.RUNTIME_USE through LocalJwtVerifyProvider:

set_authorizer(HttpUpstreamAuthProvider(...))                 # default
set_authorizer(LocalJwtVerifyProvider(secret=...),             # override
               operation=Operation.RUNTIME_USE)

require_operation(op) consults the override first, falls back to the default. The OSS path (no override installed) routes everything to HeaderAuthProvider — the no-auth flow (api_key_enabled=False) is preserved end-to-end.

Providers (three ship in-tree)

HeaderAuthProvider — local-credential path, single namespace.

• Maps each Operation to one of three access levels (PUBLIC, AUTHENTICATED, ADMIN); single source of truth in DEFAULT_OPERATION_ACCESS.
• Reuses the existing local API-key + session-cookie credential check from auth.py, so behavior matches the previous require_admin_key path verbatim.
• The no-auth flow (api_key_enabled=False) is preserved: every operation succeeds with a non-admin Principal. Pinned by a regression test.
• Always returns DEFAULT_NAMESPACE_KEY. The namespace header lookup branch is preserved but inert until non-binding write endpoints are threaded.

HttpUpstreamAuthProvider — generic upstream-delegating provider.

• Forwards caller credentials (X-API-Key, Authorization, Cookie) on a POST to a configurable URL with {operation, context?}.
• Optional service-to-service token header for upstream→authorization-service trust.
• Parses the upstream response into a Principal: namespace_key, is_admin, caller_id, plus optional grant fields (target_type, target_id, scopes, expires_at) so the runtime token exchange can mint from the same response.
• Maps 200 → Principal; 401/403/404 → matching error; 5xx, network errors, and malformed payloads fail closed (503/502).

LocalJwtVerifyProvider — hot-path runtime verifier.

• Reads a Bearer token from Authorization, verifies signature against the runtime secret, checks domain == "runtime", the issuer, expiry, and that the token's scope covers the requested Operation.
• Returns a Principal with the bound (namespace_key, target_type, target_id) so runtime endpoints inherit the namespace and target binding without re-deriving them.
• When the dependency surfaces target_type / target_id via context_builder, the provider also enforces that they match the token's binding — runtime endpoints get the request-target check for free.

Runtime token shape

HS256, dedicated secret (AGENT_CONTROL_RUNTIME_TOKEN_SECRET), issuer agent-control/server. Claims:

Claim	Purpose
domain	Pinned to runtime; tokens minted here MUST not be accepted on management endpoints.
namespace_key	The namespace the token authorizes within. Required for mint and verify; preserved end-to-end so a token minted for org A cannot be used to resolve controls in the default namespace.
actor_id	Caller identity surfaced from the upstream grant.
scopes	Granted runtime capabilities (e.g., ["runtime.use"]). The exchange endpoint refuses to mint when the upstream's explicit grant omits runtime.use.
target_type / target_id	Bind the token to one target.
iat / exp	Bounded lifetime. The local TTL is capped by the upstream grant's expires_at so the local token can never outlive its grant.
jti	Random identifier; reserved for future revocation.

Runtime token exchange endpoint

POST /api/v1/auth/runtime-token-exchange
{ "target_type": "...", "target_id": "..." }

• Authenticated and authorized via Operation.RUNTIME_TOKEN_EXCHANGE through the default authorizer (typically HttpUpstreamAuthProvider in production). The authorizer's context_builder forwards the requested target to the upstream so it can authorize against the right resource.
• Refuses with 503 when AGENT_CONTROL_RUNTIME_TOKEN_SECRET is not configured.
• Mints a local token from Principal.scopes / Principal.grant_expires_at, capped by the configured TTL (default 300s).
• When the provider's Principal carries a target binding, the endpoint verifies it matches the requested target before minting.

Response: { token, expires_at, target_type, target_id, scopes }.

Migrated endpoints

All seven /api/v1/control-bindings* endpoints now use Depends(require_operation(...)):

Method	Path	Operation
PUT	/control-bindings	control_bindings.write
GET	/control-bindings	control_bindings.read
GET	/control-bindings/{binding_id}	control_bindings.read
PATCH	/control-bindings/{binding_id}	control_bindings.write
DELETE	/control-bindings/{binding_id}	control_bindings.write
PUT	/control-bindings/by-key	control_bindings.write
POST	/control-bindings/by-key:delete	control_bindings.write

New: POST /api/v1/auth/runtime-token-exchange (operation runtime.token_exchange).

Env vars

Var	Default	Purpose
AGENT_CONTROL_AUTH_MODE	header	Default authorizer: header or http_upstream.
AGENT_CONTROL_AUTH_UPSTREAM_URL	—	Required when mode is http_upstream.
AGENT_CONTROL_AUTH_UPSTREAM_TIMEOUT_SECONDS	5.0	Per-request timeout.
AGENT_CONTROL_AUTH_UPSTREAM_SERVICE_TOKEN	—	Optional upstream service token.
AGENT_CONTROL_AUTH_UPSTREAM_SERVICE_TOKEN_HEADER	X-Agent-Control-Service-Token	Header name for the service token.
AGENT_CONTROL_RUNTIME_TOKEN_SECRET	—	Required to enable runtime auth + the exchange endpoint.
AGENT_CONTROL_RUNTIME_TOKEN_TTL_SECONDS	300	Local token TTL ceiling (capped further by the upstream grant).

Out of scope (follow-ups)

• Migrate /controls CRUD onto require_operation using the reserved CONTROLS_* operations.
• Wire Operation.RUNTIME_USE on the runtime resolution path (/evaluation, etc.) and the SDK side of the runtime exchange. The provider override is already in place when the runtime secret is configured. With feat(server): namespace scoping and control bindings #203's merged-resolver contract on /evaluation, the JWT-verified target binding now narrows the effective set the resolver returns; the verifier's match check is load-bearing for correctness, not just for authorization.
• Migrate /agents/initAgent onto require_operation. The HttpUpstreamAuthProvider's context_builder should forward the request's target_type / target_id (added in feat(server): namespace scoping and control bindings #203) to the upstream so the upstream can authorize against the requested resource.
• Thread namespace resolution through the rest of the API so the namespace header lookup in HeaderAuthProvider can be turned on safely.
• Drop auth.py's require_admin_key once every management endpoint is migrated.

Stacking

Stacked on PR #203 (abhi/data-model-v1); rebased onto its current head 8f806a3 so the merged effective-controls contract (target bindings unioned with direct + policy controls, namespace_key threaded through every join) is the base this PR builds on. GET /control-bindings/effective is gone in #203, so the migration of that route went away with it; the seven surviving binding endpoints are migrated as before. Will rebase onto main once #203 merges.

Test plan

• 51 framework + endpoint tests:
  • Default coverage: every Operation member has a default access mapping (regression guard).
  • HeaderAuthProvider: PUBLIC bypass, AUTHENTICATED + ADMIN paths route to the legacy validator with the right require_admin flag, no-auth mode passes admin operations, namespace-header lookup currently inert, unknown operation raises.
  • HttpUpstreamAuthProvider: 200 happy path with realistic JSON wire shapes (ISO datetime + JSON array scopes round-trip), service token forwarding, 401/403/404 mapping, 5xx fail-closed, network-error fail-closed, strict-grant rejection on wrong-typed is_admin / malformed scopes / bad expires_at / non-string target fields, partial target grant (target_type only or target_id only) rejected, naive expires_at rejected (no tz info → fail-closed 502 at the parser instead of TypeError later in the mint path).
  • require_operation factory: routes through the installed authorizer, per-operation overrides take precedence, clearing an override falls back to the default, get_authorizer raises when nothing is set.
  • Lifecycle: reconfiguring without the runtime secret drops the previous LocalJwtVerifyProvider override; teardown clears every authorizer.
  • Runtime token mint / verify: round-trip, wrong-secret rejection, expiry rejection, TTL capped by upstream grant, management-domain token refused on runtime verify, missing-namespace rejection, already-expired upstream grant raises UpstreamGrantExpiredError instead of minting a token with an exp in the past (also covers the boundary case where expires_at == issued_at).
  • LocalJwtVerifyProvider: target-bound Principal, namespace carried from token, missing token → 401, wrong scope → 403, non-Bearer header → 401, target-context match enforcement (mismatch on type or id → 403).
  • Exchange endpoint: 503 without secret, mint when configured, target mismatch rejected (400), missing target rejected (422), grant-without-runtime-use rejected (no privilege escalation), target context forwarded to authorizer, non-default namespace propagates into the token, full exchange-then-verify round trip, already-expired upstream grant surfaces as 502 (distinct from the 503 misconfigured-server path) so the public status reflects which side the operator should investigate.
• Full server suite: 672 passed (was 621 on feat(server): namespace scoping and control bindings #203 head; +51 from new tests).
• make lint clean.
• make typecheck clean.
• make sdk-ts-generate-check clean.
• TS SDK regenerated alongside the new endpoint (auth-runtime-token-exchange, request/response models).

[codecov]

Codecov Report

❌ Patch coverage is 89.45055% with 48 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../src/agent_control_server/auth_framework/config.py	73.80%	22 Missing ⚠️
...ent_control_server/auth_framework/runtime_token.py	85.33%	11 Missing ⚠️
server/src/agent_control_server/endpoints/auth.py	87.75%	6 Missing ⚠️
...l_server/auth_framework/providers/http_upstream.py	96.62%	3 Missing ⚠️
...ntrol_server/auth_framework/providers/local_jwt.py	91.66%	3 Missing ⚠️
...agent_control_server/endpoints/control_bindings.py	82.35%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

Reject explicit empty upstream scopes

When the HTTP upstream returns an explicit empty scopes array, _UpstreamGrant becomes principal.scopes == (), so this falsey check falls into the local default and mints a token with runtime.use. That is the privilege escalation the comment is trying to avoid when an upstream grant omits runtime.use; the exchange needs to distinguish an unscoped local provider from an explicit upstream grant with no scopes before defaulting.

[namrataghadi-galileo]

Mounting these framework-protected routers without any FastAPI Security dependency removes the APIKeyHeader requirement from generated OpenAPI; require_operation only accepts Request, so make openapi-spec emits no security entry for /api/v1/control-bindings and the auth exchange route below. API docs and downstream generators will treat these protected operations as unauthenticated even though runtime still requires credentials.

[namrataghadi-galileo]

The new Auth group is only added to the generated AgentControlSDK, but the package export uses AgentControlClient from src/index.ts, and that wrapper still exposes only the existing groups. Consumers importing agent-control cannot call runtimeTokenExchange through the public client even though this generated getter exists; add the matching wrapper getter/type export.

[namrataghadi-galileo]

P1 — Major
No upper cap on AGENT_CONTROL_RUNTIME_TOKEN_TTL_SECONDS

_load_runtime_ttl_seconds validates > 0 but sets no maximum. A misconfigured AGENT_CONTROL_RUNTIME_TOKEN_TTL_SECONDS=999999999 or a copy-paste accident mints tokens valid for decades; the point of short-lived tokens is defeated. Enforce a sane cap at startup (e.g., 86400 s = 1 day). The upstream_expires_at ceiling in mint_runtime_token only helps when the upstream surfaces an expiry.

[namrataghadi-galileo]

HttpUpstreamAuthProvider silently maps all non-200/401/403/404 to 503

A 400 (bad request in the auth call), 422, or 429 (upstream rate-limited) from the upstream all become 503 Authorization service returned an unexpected response. Rate-limit errors in particular are completely hidden from the operator. At minimum, 429 should become a distinct error or be surfaced as a hint in the 503 body.