feat(server): add management-auth seam and providers (8/8)

[abhinav-galileo]

Summary

Introduces a pluggable request-auth framework. Agent Control speaks a generic Operation vocabulary on its endpoints; a provider translates those operations onto whatever auth system a deployment uses. This PR wires the management family (4 endpoints); the framework is designed to absorb the runtime, observability, and public families in follow-ups -- see TODO markers in auth/core.py.

Also adds a local end-to-end harness for validating the full stack.

Two providers ship in-tree:

• HeaderAuthProvider -- OSS / single-tenant default. Reads X-Tenant-Id, falls back to DEFAULT_TENANT_ID. Enforces the legacy OSS API-key / admin-key check per-operation via an OSS_AUTH_LEVELS map (PUBLIC / AUTHENTICATED / ADMIN), preserving existing behavior verbatim.
• HttpUpstreamAuthProvider -- forwards caller credentials (API key, JWT, cookie) to a configurable upstream URL. Adds a configurable service-to-service token. Maps upstream statuses onto 401/403/404. Fail-closed on network errors and upstream 5xx -> 503.

Tracks: sc-63146, sc-63147.

Module layout

• auth/core.py -- framework: Operation (incl. reserved runtime/observability/public members), Principal, RequestAuthorizer Protocol, require_operation(op, context_builder) FastAPI dependency factory, global authorizer registry.
• auth/local.py -- legacy OSS credential check (API key + session cookie). Still used by non-management endpoints pending follow-up migration. Also exposes authenticate_request() as a re-usable helper for providers.
• auth/providers/header.py -- OSS default, with LocalAccessLevel enum and OSS_AUTH_LEVELS map (single source of truth for OSS access policy).
• auth/providers/http_upstream.py -- upstream HTTP adapter.
• auth/config.py -- configure_auth_from_env() reads env vars at startup.

P0 fix: management endpoints accept upstream credentials

Previously the 4 management endpoints were wrapped with the router-level Depends(require_api_key) AND the endpoint-level Depends(require_admin_key), which rejected the Galileo bearer token that http_upstream mode expects to forward. They now live on dedicated management_router objects mounted in main.py without the legacy gate; the provider alone owns authn+authz.

Non-management endpoints keep their legacy gates (tagged with TODO(auth-framework) markers) and continue to work exactly as before.

Env vars

• AGENT_CONTROL_MANAGEMENT_AUTH_MODE=header (default) or http_upstream
• When http_upstream:
  • AGENT_CONTROL_MANAGEMENT_AUTH_UPSTREAM_URL (required)
  • AGENT_CONTROL_MANAGEMENT_AUTH_UPSTREAM_CHECK_PATH (default /internal/agent_control/auth/check_management_access)
  • AGENT_CONTROL_MANAGEMENT_AUTH_UPSTREAM_SERVICE_TOKEN (optional)
  • AGENT_CONTROL_MANAGEMENT_AUTH_UPSTREAM_SERVICE_TOKEN_HEADER (default X-Agent-Control-Service-Token)
  • AGENT_CONTROL_MANAGEMENT_AUTH_UPSTREAM_TIMEOUT_SECONDS (default 5.0)

Wired endpoints

• GET /api/v1/controls -> controls.read
• GET /api/v1/targets/{target_type}/{external_id}/controls -> target_bindings.read
• PUT /api/v1/targets/{target_type}/{external_id}/controls/{control_id} -> target_bindings.write
• DELETE /api/v1/targets/{target_type}/{external_id}/controls/{control_id} -> target_bindings.write

Each endpoint uses Depends(require_operation(...)) and reads tenant_id from the returned Principal. For target-binding routes a _target_binding_context builder extracts target_type and external_id from request.path_params.

OSS-safe

No Galileo or Cerbos nouns in auth/core.py or auth/providers/header.py. Provider-specific logic lives only in providers/http_upstream.py. Any HTTP service that speaks the documented operation contract can be an upstream.

End-to-end harness

tools/management_vertical_harness/harness.py -- reproducible validation script for a locally-running stack of Agent Control, Galileo api, and Galileo authz. Walks the happy path and three optional deny cases. Useful for manual integration validation without a UI.

See tools/management_vertical_harness/README.md for usage.

Tests

• tests/test_auth_framework.py -- 9 unit tests:
  • Header provider: resolve from header, fall back to default, trim whitespace (with api_key_enabled=False so the credential check passes through).
  • HTTP upstream provider: credential forwarding, service-token injection, 401/403/404 mapping, 5xx fail-closed, network-error fail-closed, malformed principal -> 502.
  • require_operation dependency factory routes operation + context to the installed authorizer.
• conftest.py autouse fixture installs HeaderAuthProvider so isolated test subsets (no lifespan) still have an authorizer.

Test plan

• Full server suite -- 616 passed
• mypy clean
• ruff clean on touched files

Stacking

Based on abhi/rfc-1-1-pr7-natural-key-attach (PR7). Pairs with rungalileo/authz#145 and rungalileo/api#6350 for the Galileo-hosted deployment mode.

[codecov]

Codecov Report

❌ Patch coverage is 88.26291% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ent_control_server/auth/providers/http_upstream.py	82.85%	12 Missing ⚠️
server/src/agent_control_server/auth/config.py	66.66%	11 Missing ⚠️
server/src/agent_control_server/auth/core.py	97.14%	1 Missing ⚠️
.../src/agent_control_server/auth/providers/header.py	96.15%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!