Totoro b0bca9dcb4
feat(mcp): bind HTTP tool credentials to approved custom agents (#8242)
* feat(mcp): bind agent credentials to approved definitions

* fix(mcp): enforce live auth policy and pin task destinations

---------

Co-authored-by: Totoro-qaq <279883115+Totoro-qaq@users.noreply.github.com>
2026-11-14 22:10:33 +08:00

257 lines
12 KiB
Python

"""Host-admitted agent identities for deployment MCP calls."""
from __future__ import annotations
import asyncio
import logging
import threading
from collections import OrderedDict
from collections.abc import Iterator, Mapping
from contextlib import contextmanager
from contextvars import ContextVar
from dataclasses import dataclass
from typing import Any, Literal
from deerflow_extension_api import canonical_hash, canonical_json
from langchain_core.tools import ToolException
from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
from deerflow.config.agents_config import AgentConfig, load_agent_soul
from deerflow.config.extensions_config import ExtensionsConfig, McpServerConfig, get_extensions_config
from deerflow.config.mcp_agent_auth_config import BindingId, DefinitionDigest, McpAgentCredentialBinding
from deerflow.mcp.headers import apply_header_overrides, header_spellings
from deerflow.mcp.oauth import OAuthTokenManager
from deerflow.runtime.context_keys import AGENT_AUTH_CONTEXT_KEY
from deerflow.runtime.user_context import resolve_runtime_user_id
logger = logging.getLogger(__name__)
class McpAgentAuthorizationError(ToolException):
"""An agent's administrator grant is absent, revoked or replaced."""
class AgentCredentialReference(BaseModel):
"""Nonsecret identity retained by a durable task."""
model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
version: Literal[1] = 1
server: str
binding: BindingId
agent: str
definition_digest: DefinitionDigest
credential_digest: DefinitionDigest
destination_digest: DefinitionDigest
@dataclass(frozen=True)
class AgentMcpAuthority:
user_id: str
references: tuple[AgentCredentialReference, ...]
definition_json: str | None = None
soul: str = ""
def agent_config(self) -> AgentConfig | None:
return AgentConfig.model_validate_json(self.definition_json) if self.definition_json is not None else None
_task_authority: ContextVar[AgentMcpAuthority | None] = ContextVar("deerflow_mcp_task_agent_authority", default=None)
_reference_list = TypeAdapter(list[AgentCredentialReference])
_token_managers: OrderedDict[tuple[str, str, str], OAuthTokenManager] = OrderedDict()
_token_managers_lock = threading.Lock()
def agent_definition_digest(config: AgentConfig, soul: str | None) -> str:
"""Hash the stored agent settings and SOUL text that admission will pin."""
return canonical_hash({"version": 1, "config": config.model_dump(mode="json"), "soul": soul or ""})
def _credential_digest(binding: McpAgentCredentialBinding) -> str:
# Rotating a secret preserves the account. Replacing the endpoint, client,
# scope or other request settings requires a new admission.
return canonical_hash(binding.oauth.model_dump(mode="json", exclude={"client_secret", "refresh_token", "refresh_skew_seconds"}))
def _destination_digest(server: McpServerConfig) -> str:
return canonical_hash({"transport": server.type, "url": server.url})
def _current_server(server_name: str) -> McpServerConfig | None:
from deerflow.config.app_config import get_app_config, peek_loaded_app_config
try:
# Standalone MCP clients need only extensions_config.json. A Gateway
# also applies its operator-owned YAML overrides, never a run snapshot.
config = get_app_config(use_runtime_override=False).extensions if peek_loaded_app_config(use_runtime_override=False) is not None else get_extensions_config()
return config.mcp_servers.get(server_name)
except Exception:
raise ToolException("MCP agent credential policy is unavailable") from None
def capture_agent_authority(app_config: Any, *, user_id: str, agent_config: AgentConfig | None) -> AgentMcpAuthority | None:
"""Admit a host-loaded definition once, before an agent run is assembled."""
if agent_config is None:
return None
matches = []
for binding_id, binding in app_config.mcp_agent_auth.items():
server = app_config.extensions.mcp_servers.get(binding.server)
if binding.enabled and binding.agent == agent_config.name and user_id in binding.owners and server is not None and server.enabled and server.agent_auth:
matches.append((binding_id, binding))
if not matches:
return None
soul = load_agent_soul(agent_config.name, user_id=user_id) or ""
digest = agent_definition_digest(agent_config, soul)
references = []
for binding_id, binding in matches:
if digest not in binding.definition_digests:
raise McpAgentAuthorizationError(f"Agent definition is not approved for MCP binding '{binding_id}'")
references.append(
AgentCredentialReference(
server=binding.server,
binding=binding_id,
agent=binding.agent,
definition_digest=digest,
credential_digest=_credential_digest(binding),
destination_digest=_destination_digest(app_config.extensions.mcp_servers[binding.server]),
)
)
return AgentMcpAuthority(user_id, tuple(references), canonical_json(agent_config.model_dump(mode="json")), soul)
def runtime_agent_authority(runtime: Any) -> AgentMcpAuthority | None:
context = getattr(runtime, "context", None)
authority = context.get(AGENT_AUTH_CONTEXT_KEY) if isinstance(context, Mapping) else None
if isinstance(authority, AgentMcpAuthority) and authority.user_id == resolve_runtime_user_id(runtime):
return authority
return None
def export_agent_authority(authority: AgentMcpAuthority | None) -> list[dict[str, Any]] | None:
"""Persist references captured by the host, without definitions or credentials."""
if not isinstance(authority, AgentMcpAuthority):
return None
return [reference.model_dump(mode="json") for reference in authority.references]
def restore_agent_authority(user_id: str, references: Any) -> AgentMcpAuthority | None:
"""Restore references from host-owned durable rows; each use rechecks the grant."""
if references is None:
return None
try:
parsed = _reference_list.validate_python(references)
except ValidationError:
raise McpAgentAuthorizationError("Invalid persisted MCP agent identity") from None
if not parsed or len({ref.server for ref in parsed}) != len(parsed) or len({ref.agent for ref in parsed}) != 1:
raise McpAgentAuthorizationError("Invalid persisted MCP agent identity")
return AgentMcpAuthority(user_id, tuple(parsed))
def task_agent_reference(runtime: Any, server_name: str, *, required: bool) -> dict[str, Any] | None:
authority = runtime_agent_authority(runtime)
if authority is not None:
for reference in authority.references:
if reference.server == server_name:
return reference.model_dump(mode="json")
if required:
raise McpAgentAuthorizationError(f"No admitted agent credential for MCP server '{server_name}'")
return None
def _current_binding(reference: AgentCredentialReference, user_id: str) -> McpAgentCredentialBinding:
from deerflow.config.app_config import get_app_config
try:
config = get_app_config(use_runtime_override=False)
except Exception:
raise ToolException("MCP agent credential policy is unavailable") from None
binding = config.mcp_agent_auth.get(reference.binding)
server = config.extensions.mcp_servers.get(reference.server)
if (
binding is None
or not binding.enabled
or user_id not in binding.owners
or binding.server != reference.server
or binding.agent != reference.agent
or server is None
or not server.enabled
or not server.agent_auth
or _destination_digest(server) != reference.destination_digest
or _credential_digest(binding) != reference.credential_digest
):
raise McpAgentAuthorizationError(f"MCP agent credential binding '{reference.binding}' is unavailable or revoked")
# Definition rollout changes admission for new runs. Existing calls and
# durable tasks retain the definition version recorded at their admission.
return binding
def _token_manager(reference: AgentCredentialReference, binding: McpAgentCredentialBinding) -> OAuthTokenManager:
key = (reference.server, reference.binding, canonical_hash(binding.oauth.model_dump(mode="json")))
with _token_managers_lock:
manager = _token_managers.get(key)
if manager is None:
manager = OAuthTokenManager({reference.server: binding.oauth})
_token_managers[key] = manager
_token_managers.move_to_end(key)
if len(_token_managers) > 128:
_token_managers.popitem(last=False)
return manager
@contextmanager
def bind_task_agent_authority(authority: AgentMcpAuthority | None) -> Iterator[None]:
token = _task_authority.set(authority)
try:
yield
finally:
_task_authority.reset(token)
async def validate_task_agent_reference(user_id: str, server_name: str, reference: Any) -> AgentMcpAuthority | None:
authority = restore_agent_authority(user_id, [reference]) if reference is not None else None
if authority is not None:
admitted = authority.references[0]
if admitted.server != server_name:
raise McpAgentAuthorizationError("MCP task credential belongs to a different server")
await asyncio.to_thread(_current_binding, admitted, user_id)
return authority
def build_agent_auth_interceptor(extensions_config: ExtensionsConfig) -> Any | None:
servers = {name: server for name, server in extensions_config.get_enabled_mcp_servers().items() if server.type in ("http", "sse")}
if not servers:
return None
async def agent_auth_interceptor(request: Any, handler: Any) -> Any:
server = servers.get(request.server_name)
if server is None:
return await handler(request)
if not server.agent_auth:
current = await asyncio.to_thread(_current_server, request.server_name)
if current is not None and current.agent_auth:
# The old chain may still contain user/context auth writers.
# Require rediscovery instead of injecting into that chain.
raise McpAgentAuthorizationError(f"MCP server '{request.server_name}' now requires agent credentials; start a new run to reload its tools")
return await handler(request)
runtime = getattr(request, "runtime", None)
authority = runtime_agent_authority(runtime) if runtime is not None else _task_authority.get()
reference = next((ref for ref in authority.references if ref.server == request.server_name), None) if authority is not None else None
if reference is None:
raise McpAgentAuthorizationError(f"No admitted agent credential for MCP server '{request.server_name}'")
if _destination_digest(server) != reference.destination_digest:
raise McpAgentAuthorizationError(f"MCP destination no longer matches binding '{reference.binding}'")
binding = await asyncio.to_thread(_current_binding, reference, authority.user_id)
manager = _token_manager(reference, binding)
try:
authorization = await manager.get_authorization_header(reference.server)
except Exception:
raise ToolException(f"Could not acquire the agent credential for MCP server '{reference.server}'") from None
if not authorization:
raise ToolException(f"Missing agent credential for MCP server '{reference.server}'")
# Token acquisition may await an external identity provider.
await asyncio.to_thread(_current_binding, reference, authority.user_id)
logger.info("MCP agent credential selected for server=%s agent=%s owner=%s binding=%s", reference.server, reference.agent, authority.user_id, reference.binding)
headers = apply_header_overrides(request.headers, {"Authorization": authorization}, spellings=header_spellings(server.headers))
return await handler(request.override(headers=headers))
return agent_auth_interceptor