feat(server): add runtime auth and namespace scoping

[abhinav-galileo]

Summary

• Add explicit runtime auth modes: none, api_key, and jwt.
• Scope controls, bindings, policies, agents, and evaluation by the authenticated principal namespace.
• Authorize runtime token exchange and runtime evaluation with target context.
• Add configurable extra forwarded headers for HTTP upstream auth.

Stack

• Based on feat(server): migrate controls routes to auth framework #212.

Testing

• make prepush on the stacked branch in feat(sdk): add runtime token auth #215.

[codecov]

Codecov Report

❌ Patch coverage is 94.73684% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../src/agent_control_server/auth_framework/config.py	93.22%	4 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.15%	4 Missing ⚠️
...r/src/agent_control_server/endpoints/evaluation.py	69.23%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

P1:
Line 58-76:
Target-binding check is conditional on the request supplying a target, not on the token carrying one. Today a runtime token bound to (env, prod) will pass authorization for /api/v1/evaluation if the caller simply omits target_type/target_id from the body — evaluation_context returns {"target_type": None, "target_id": None}, and lines 61/69 short-circuit on the requested_target* is not None guard. EvaluationRequest.target_type is Optional ([models/evaluation.py:46], so Pydantic will not reject this. Net effect: a target-bound token can be used for a namespace-wide eval that ignores the binding.

Suggested fix — invert the check so the token's binding is the source of truth:

if claims.target_type is not None or claims.target_id is not None:
    if context is None:
        raise ForbiddenError(...)
    if context.get("target_type") != claims.target_type:
        raise ForbiddenError("target_type does not match")
    if context.get("target_id") != claims.target_id:
        raise ForbiddenError("target_id does not match")

Add a regression test in test_runtime_token_exchange_endpoint.py next to test_evaluation_rejects_runtime_jwt_for_wrong_target that omits target_type/target_id from the eval body and asserts 403.

[abhinav-galileo]

Fixed in d0dd12c. The verifier now treats the token binding as authoritative, so missing or mismatched request target context is denied. Added a regression test for target-less evaluation.

[namrataghadi-galileo]

Two routers were left on the legacy Depends(require_api_key) gate — evaluator_router (with the new "Evaluator discovery still uses the local credential dependency." comment) and observability_router. That means AGENT_CONTROL_AUTH_MODE=none and AGENT_CONTROL_AUTH_MODE=http_upstream silently do not apply to either route. An operator running in upstream-auth mode will still find /api/v1/evaluators / /api/v1/observability/... requiring an X-API-Key, and a none-mode deployment will return 401 from these even though the rest of the API is open.

Either migrate them in this PR (each is a one-line require_operation swap with a new EVALUATORS_READ / OBSERVABILITY_WRITE Operation member), or land a follow-up issue link in the comment so the deferral is explicit, not implied.

[namrataghadi-galileo]

Same applies to server/endpoints/observability line 45

[abhinav-galileo]

Agreed this should be explicit. I am leaving evaluator discovery and observability on the existing local-credential gate in this stack because migrating them adds new generic operation names to the upstream auth contract. I will track that as a separate auth-framework follow-up.

[abhinav-galileo]

Covered in the parent thread. Same follow-up: observability needs a generic operation added before moving it to the provider contract.

[abhinav-galileo]

Done in this stack. Evaluator discovery and observability now declare explicit auth-framework operations (evaluators.read, observability.read, observability.write). The router-level API-key extractor is kept only for OpenAPI security metadata, while local API-key mode preserves the previous authenticated-access behavior.

[namrataghadi-galileo]

except Exception swallows every parse failure and returns {}, so a malformed body removes the target check from the runtime authorizer entirely (cf. Comment 1 above). FastAPI's body validator will eventually 422 the request, but the authorizer has already accepted the token by then — useful signal lost from logs, and harder to spot if the auth ordering ever changes.

Suggested: narrow the catch to (json.JSONDecodeError, UnicodeDecodeError), log at debug, and once Comment 1 lands the fail-open hole closes for free. Don't widen _evaluation_context to enforce — keep the policy in LocalJwtVerifyProvider, the context builder should just supply data.

[abhinav-galileo]

Fixed in d0dd12c. The context builder now only catches JSON/Unicode decode failures and logs at debug; target enforcement stays in the JWT provider.

[namrataghadi-galileo]

The new test pins create / list / get / delete cross-namespace isolation, but skips the mutating verbs on controls (PATCH /controls/{id}, PUT /controls/{id}/data), the binding by-key paths (PUT /control-bindings/by-key, POST /control-bindings/by-key:delete), and the agent association endpoints (POST /agents/{name}/policies/{policy_id} etc.). Each of those threads principal.namespace_key independently and a future refactor that drops the kwarg on one of them won't be caught.

Suggested: parametrize a single test_namespace_isolation_for_writes over (method, url, payload) tuples covering PATCH /controls, PUT /controls/{id}/data, PUT /control-bindings/by-key, POST /agents/{name}/policies/{policy_id}, and POST /agents/{name}/controls/{control_id} — assert each rejects (404 or empty list) when called from ns-b for an ns-a resource. ~40 lines.

[abhinav-galileo]

Added coverage in d0dd12c for the cross-namespace write paths: control patch/data update, binding by-key upsert/delete, and agent policy/control associations.

[namrataghadi-galileo]

The sibling get_active_control_or_404 was tightened to make namespace_key required in this PR ([line 163], but get_control_or_404 still accepts namespace_key: str | None = None. Both internal callers (lines 240, 279) pass it, so making it required is a no-op today but closes the door on a future caller forgetting it.

Suggested: drop the default and make the parameter required, same as get_active_control_or_404.

[abhinav-galileo]

Fixed in d0dd12c. get_control_or_404 now requires namespace_key and always scopes the query by it.

[namrataghadi-galileo]

_build_default_provider accepts header as an alias for api_key (good, backwards-compatible), but the RuntimeError lists only 'none', 'api_key', or 'http_upstream' — operators reading the error after a typo will think header is invalid. Same nit for _resolve_runtime_mode. Add 'header' to the error string, or drop the alias from the accepted set if you intend to retire it.

[abhinav-galileo]

Fixed in d0dd12c. The accepted-mode error text now includes header wherever the alias is accepted.