feat(server): add runtime auth and namespace scoping (#214)

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
+- [Authentication](https://docs.agentcontrol.dev/core/authentication) — 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

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):
         ),
     )
 
-

sdks/typescript/src/generated/funcs/agents-get-evaluator.ts

@@ -37,8 +37,7 @@ import { Result } from "../types/fp.js";
  *     agent_name: Agent identifier
  *     evaluator_name: Name of the evaluator
  *     db: Database session (injected)
- *     namespace_key: Resolved namespace; agents in another namespace
- *         return 404 (non-disclosing).
+ *     principal: Authorized request principal
  *
  * Returns:
  *     EvaluatorSchemaItem with schema details

sdks/typescript/src/generated/funcs/agents-get.ts

@@ -38,8 +38,7 @@ import { Result } from "../types/fp.js";
  * Args:
  *     agent_name: Agent identifier
  *     db: Database session (injected)
- *     namespace_key: Resolved namespace; agents in another namespace
- *         return 404 (non-disclosing).
+ *     principal: Authorized request principal
  *
  * Returns:
  *     GetAgentResponse with agent metadata and step list

sdks/typescript/src/generated/funcs/agents-init.ts

@@ -51,6 +51,8 @@ import { Result } from "../types/fp.js";
  * Args:
  *     request: Agent metadata and step schemas
  *     db: Database session (injected)
+ *     principal: Authorized request principal for the agent create operation
+ *     target_principal: Optional principal from the target binding read check
  *
  * Returns:
  *     InitAgentResponse with created flag and the effective controls

sdks/typescript/src/generated/funcs/agents-list-controls.ts

@@ -53,7 +53,8 @@ import { Result } from "../types/fp.js";
  *     target_type: Optional opaque target kind (paired with target_id)
  *     target_id: Optional opaque target identifier (paired with target_type)
  *     db: Database session (injected)
- *     namespace_key: Namespace scoping for the resolution (injected)
+ *     principal: Authorized request principal for the agent read operation
+ *     target_principal: Optional principal from the target binding read check
  *
  * Returns:
  *     AgentControlsResponse with controls matching the requested state filters

sdks/typescript/src/generated/funcs/agents-list-evaluators.ts

@@ -42,8 +42,7 @@ import { Result } from "../types/fp.js";
  *     cursor: Optional cursor for pagination (name of last evaluator from previous page)
  *     limit: Pagination limit (default 20, max 100)
  *     db: Database session (injected)
- *     namespace_key: Resolved namespace; agents in another namespace
- *         return 404 (non-disclosing).
+ *     principal: Authorized request principal
  *
  * Returns:
  *     ListEvaluatorsResponse with evaluator schemas and pagination

sdks/typescript/src/generated/funcs/agents-list.ts

@@ -42,7 +42,7 @@ import { Result } from "../types/fp.js";
  *     limit: Pagination limit (default 20, max 100)
  *     name: Optional name filter (case-insensitive partial match)
  *     db: Database session (injected)
- *     namespace_key: Resolved namespace for the request
+ *     principal: Authorized request principal
  *
  * Returns:
  *     ListAgentsResponse with agent summaries and pagination info

sdks/typescript/src/generated/funcs/agents-update.ts

@@ -40,6 +40,7 @@ import { Result } from "../types/fp.js";
  *     agent_name: Agent identifier
  *     request: Lists of step/evaluator identifiers to remove
  *     db: Database session (injected)
+ *     principal: Authorized request principal
  *
  * Returns:
  *     PatchAgentResponse with lists of actually removed items

sdks/typescript/src/generated/funcs/auth-runtime-token-exchange.ts

@@ -32,11 +32,10 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Mint a short-lived runtime token for the requested target.
  *
- * The caller's credential is authenticated and authorized by the
- * installed default authorizer; the resulting :class:`Principal`
- * supplies the actor identity and (when the upstream surfaces it)
- * the grant scopes and expiry. This endpoint then mints a local HS256
- * token whose lifetime cannot outlive the upstream grant.
+ * The caller's credential is authenticated and authorized before the
+ * resolved principal supplies the actor identity, grant scopes, and
+ * expiry. This endpoint then mints a local HS256 token whose lifetime
+ * cannot outlive the grant.
  *
  * Runtime auth must be enabled via
  * ``AGENT_CONTROL_RUNTIME_TOKEN_SECRET``; otherwise the endpoint