fix(server): harden auth scoping

Author: abhinav-galileo

docs/README.md

@@ -10,6 +10,7 @@ This repository keeps documentation concise. The full documentation lives on the
 - [Controls](https://docs.agentcontrol.dev/concepts/controls) — Define and configure control rules
 - [Reference](https://docs.agentcontrol.dev/core/reference) — SDK and server API reference
 - [Configuration](https://docs.agentcontrol.dev/core/configuration) — Environment variables, auth, and database settings
+- [Server auth contract](auth.md) - Pluggable auth modes, HTTP upstream contract, and runtime JWT claims
 - [UI Quickstart](https://docs.agentcontrol.dev/core/ui-quickstart) — Run the dashboard and manage controls visually
 
 ## Examples

docs/auth.md

@@ -0,0 +1,148 @@
+# Server Auth Contract
+
+Agent Control keeps authentication and authorization provider-neutral. The server asks a configured provider whether a request may perform an operation, then scopes all data access with the returned `Principal`.
+
+## Operations
+
+Operations are stable strings. Deployers map them to their own permission model.
+
+```text
+controls.read
+controls.create
+controls.update
+controls.delete
+policies.read
+policies.create
+policies.update
+agents.read
+agents.create
+agents.update
+control_bindings.read
+control_bindings.write
+runtime.token_exchange
+runtime.use
+```
+
+## Principal
+
+Providers return a generic principal. Agent Control treats `namespace_key`, `caller_id`, `target_type`, and `target_id` as opaque strings.
+
+```json
+{
+  "namespace_key": "tenant-a",
+  "is_admin": false,
+  "caller_id": "user-or-key-id",
+  "target_type": "session",
+  "target_id": "target-123",
+  "scopes": ["runtime.use"],
+  "expires_at": "2026-05-11T15:00:00Z"
+}
+```
+
+`namespace_key` is the tenancy boundary. Server queries filter by it, and namespace-aware foreign keys prevent cross-namespace references.
+
+## Auth Modes
+
+Management auth is selected by `AGENT_CONTROL_AUTH_MODE`.
+
+| Mode | Meaning |
+| --- | --- |
+| `none` | No credentials required. Intended for local development only. |
+| `api_key` | Validate caller credentials locally with `AGENT_CONTROL_API_KEYS`. This is the default. `header` is accepted as a backwards-compatible alias. |
+| `http_upstream` | POST each management authorization decision to `AGENT_CONTROL_AUTH_UPSTREAM_URL`. |
+
+Runtime auth is selected by `AGENT_CONTROL_RUNTIME_AUTH_MODE`.
+
+| Mode | Meaning |
+| --- | --- |
+| unset | Use `jwt` when `AGENT_CONTROL_RUNTIME_TOKEN_SECRET` is set. Otherwise runtime requests fall through to management auth. |
+| `none` | No runtime credentials required. Intended for local development only. |
+| `api_key` | Validate runtime requests with the same local API-key mechanism. |
+| `jwt` | Require target-bound runtime tokens minted by `/api/v1/auth/runtime-token-exchange`. |
+
+Common combinations:
+
+| Management | Runtime | Use case |
+| --- | --- | --- |
+| `api_key` | unset | Existing standalone deployments. |
+| `api_key` | `jwt` | Local management keys with short-lived target-bound runtime tokens. |
+| `http_upstream` | `jwt` | External identity or authorization service for management, local token verify for high-volume runtime calls. |
+| `none` | `none` | Single-process local development. Do not use in production. |
+
+## HTTP Upstream Contract
+
+When `AGENT_CONTROL_AUTH_MODE=http_upstream`, the server sends:
+
+```http
+POST {AGENT_CONTROL_AUTH_UPSTREAM_URL}
+```
+
+```json
+{
+  "operation": "control_bindings.write",
+  "context": {
+    "target_type": "session",
+    "target_id": "target-123"
+  }
+}
+```
+
+The provider forwards inbound `X-API-Key`, `Authorization`, and `Cookie` headers. Add deployer-specific header names with `AGENT_CONTROL_AUTH_UPSTREAM_EXTRA_FORWARD_HEADERS`, for example:
+
+```text
+AGENT_CONTROL_AUTH_UPSTREAM_EXTRA_FORWARD_HEADERS=Vendor-API-Key,X-Workspace-Id
+```
+
+If `AGENT_CONTROL_AUTH_UPSTREAM_SERVICE_TOKEN` is set, it is forwarded on `AGENT_CONTROL_AUTH_UPSTREAM_SERVICE_TOKEN_HEADER` or `X-Agent-Control-Service-Token` by default.
+
+A successful upstream response is:
+
+```json
+{
+  "namespace_key": "tenant-a",
+  "is_admin": false,
+  "caller_id": "user-or-key-id",
+  "target_type": "session",
+  "target_id": "target-123",
+  "scopes": ["runtime.use"],
+  "expires_at": "2026-05-11T15:00:00Z"
+}
+```
+
+Only `namespace_key` is always required. `target_type` and `target_id` must be returned together when present. `expires_at` must include timezone information.
+
+Status handling:
+
+| Upstream status | Agent Control result |
+| --- | --- |
+| `200` | Parse the principal grant. |
+| `401` | Authentication error. |
+| `403` | Forbidden error. |
+| `404` | Not found error. |
+| `429` | `503` with a rate-limit detail and `Retry-After` hint when present. |
+| Other statuses or malformed JSON | Fail closed with `503` or `502`. |
+
+## Runtime JWT Claims
+
+`/api/v1/auth/runtime-token-exchange` is a management-style request. The configured management provider authorizes `runtime.token_exchange` for the requested target. Agent Control then mints its own HS256 JWT with `AGENT_CONTROL_RUNTIME_TOKEN_SECRET`.
+
+The token payload contains:
+
+```json
+{
+  "iss": "agent-control/server",
+  "domain": "runtime",
+  "namespace_key": "tenant-a",
+  "actor_id": "user-or-key-id",
+  "target_type": "session",
+  "target_id": "target-123",
+  "scopes": ["runtime.use"],
+  "iat": 1778509800,
+  "exp": 1778510100,
+  "jti": "opaque-token-id"
+}
+```
+
+Verification requires the expected issuer, `domain="runtime"`, a valid signature, an unexpired `exp`, and `runtime.use` in `scopes`. The token is accepted only for requests whose `target_type` and `target_id` match the bound target.
+
+The expiry is the earlier of `AGENT_CONTROL_RUNTIME_TOKEN_TTL_SECONDS` and the upstream grant's `expires_at` when supplied. Runtime token TTLs are capped at 86400 seconds.

models/src/agent_control_models/server.py

@@ -640,7 +640,7 @@ class CreateControlBindingRequest(BaseModel):
 
     target_type: ControlBindingTargetField = Field(
         ...,
-        description="Opaque attachment kind (caller-defined; e.g. 'env', 'log_stream').",
+        description="Opaque attachment kind (caller-defined; e.g. 'environment', 'session').",
     )
     target_id: ControlBindingTargetField = Field(
         ..., description="Opaque external identifier within the target_type."
@@ -760,4 +760,3 @@ class DeleteControlBindingByKeyResponse(BaseModel):
         ),
     )
 
-

server/src/agent_control_server/endpoints/agents.py

@@ -29,20 +29,21 @@
     SetPolicyResponse,
     StepKey,
 )
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, Query, Request
 from jsonschema_rs import ValidationError as JSONSchemaValidationError
 from pydantic import BaseModel, ValidationError
 from sqlalchemy import delete, func, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from ..auth_framework import Operation, Principal, require_operation
+from ..auth_framework import Operation, Principal, get_authorizer, require_operation
 from ..db import get_async_db
 from ..errors import (
     APIValidationError,
     BadRequestError,
     ConflictError,
     DatabaseError,
+    ForbiddenError,
     NotFoundError,
 )
 from ..logging_utils import get_logger
@@ -85,6 +86,81 @@
 type StepKeyTuple = tuple[str, str]
 
 
+def _complete_target_context(
+    target_type: object | None,
+    target_id: object | None,
+) -> dict[str, str] | None:
+    """Return target context only when both halves are present strings."""
+    if not isinstance(target_type, str) or not isinstance(target_id, str):
+        return None
+    if not target_type or not target_id:
+        return None
+    return {"target_type": target_type, "target_id": target_id}
+
+
+async def _init_agent_target_context(request: Request) -> dict[str, str] | None:
+    """Extract optional target context from an ``initAgent`` body."""
+    try:
+        body = await request.json()
+    except Exception:  # noqa: BLE001  malformed JSON, defer to endpoint validation
+        return None
+    if not isinstance(body, dict):
+        return None
+    return _complete_target_context(body.get("target_type"), body.get("target_id"))
+
+
+def _agent_controls_target_context(request: Request) -> dict[str, str] | None:
+    """Extract optional target context from ``GET /agents/{name}/controls``."""
+    return _complete_target_context(
+        request.query_params.get("target_type"),
+        request.query_params.get("target_id"),
+    )
+
+
+async def _authorize_target_read_if_present(
+    request: Request,
+    context: dict[str, str] | None,
+) -> Principal | None:
+    """Require target read authorization before returning target-merged controls."""
+    if context is None:
+        return None
+    return await get_authorizer(Operation.CONTROL_BINDINGS_READ).authorize(
+        request,
+        Operation.CONTROL_BINDINGS_READ,
+        context,
+    )
+
+
+async def _init_agent_target_principal(request: Request) -> Principal | None:
+    return await _authorize_target_read_if_present(
+        request,
+        await _init_agent_target_context(request),
+    )
+
+
+async def _agent_controls_target_principal(request: Request) -> Principal | None:
+    return await _authorize_target_read_if_present(
+        request,
+        _agent_controls_target_context(request),
+    )
+
+
+def _ensure_target_principal_matches_namespace(
+    principal: Principal,
+    target_principal: Principal | None,
+) -> None:
+    """Fail closed if the target authorization resolves to a different namespace."""
+    if target_principal is None:
+        return
+    if target_principal.namespace_key == principal.namespace_key:
+        return
+    raise ForbiddenError(
+        error_code=ErrorCode.AUTH_INSUFFICIENT_PRIVILEGES,
+        detail="Target authorization resolved to a different namespace.",
+        hint="Ensure the credential is scoped to the requested target and namespace.",
+    )
+
+
 # =============================================================================
 # List Agents Models
 # =============================================================================
@@ -445,6 +521,7 @@ async def init_agent(
     request: InitAgentRequest,
     db: AsyncSession = Depends(get_async_db),
     principal: Principal = Depends(require_operation(Operation.AGENTS_CREATE)),
+    target_principal: Principal | None = Depends(_init_agent_target_principal),
 ) -> InitAgentResponse:
     """
     Register a new agent or update an existing agent's steps and metadata.
@@ -474,6 +551,7 @@ async def init_agent(
         InitAgentResponse with created flag and the effective controls
     """
     namespace_key = principal.namespace_key
+    _ensure_target_principal_matches_namespace(principal, target_principal)
 
     # Check for evaluator name collisions with built-in evaluators
     builtin_names = _get_builtin_evaluator_names()
@@ -1493,6 +1571,7 @@ async def list_agent_controls(
     ),
     db: AsyncSession = Depends(get_async_db),
     principal: Principal = Depends(require_operation(Operation.AGENTS_READ)),
+    target_principal: Principal | None = Depends(_agent_controls_target_principal),
 ) -> AgentControlsResponse:
     """
     List protection controls effective for an agent.
@@ -1527,6 +1606,7 @@ async def list_agent_controls(
         HTTPException 404: Agent not found
     """
     namespace_key = principal.namespace_key
+    _ensure_target_principal_matches_namespace(principal, target_principal)
 
     if (target_type is None) != (target_id is None):
         raise BadRequestError(

server/src/agent_control_server/endpoints/auth.py

@@ -28,8 +28,10 @@
     mint_runtime_token,
 )
 from ..errors import APIError, BadRequestError
+from ..logging_utils import get_logger
 
 router = APIRouter(prefix="/auth", tags=["auth"])
+_logger = get_logger(__name__)
 
 
 class RuntimeTokenExchangeRequest(BaseModel):
@@ -38,7 +40,7 @@ class RuntimeTokenExchangeRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     target_type: str = Field(
-        ..., description="Opaque target kind (e.g., ``log_stream``).", min_length=1
+        ..., description="Opaque target kind (e.g., ``session``).", min_length=1
     )
     target_id: str = Field(..., description="Opaque target identifier.", min_length=1)
 
@@ -175,6 +177,19 @@ async def runtime_token_exchange(
             hint="Check the runtime token configuration.",
         ) from exc
 
+    _logger.info(
+        "Runtime token exchanged",
+        extra={
+            "namespace_key": claims.namespace_key,
+            "actor_id": claims.actor_id,
+            "target_type": claims.target_type,
+            "target_id": claims.target_id,
+            "scopes": list(claims.scopes),
+            "expires_at": claims.expires_at.isoformat(),
+            "jti": claims.jti,
+        },
+    )
+
     return RuntimeTokenExchangeResponse(
         token=token,
         expires_at=claims.expires_at,