From e7f1f0197bfb60b0b508d7ccfc1f7a0b3609f9f5 Mon Sep 17 00:00:00 2001 From: yassin Date: Tue, 22 Sep 2026 00:39:25 +0000 Subject: [PATCH] fix(proxy): deny agent requests whose invoking caller cannot be resolved An echoed x-litellm-team-id or x-litellm-user-id that names no row, or a known team with no grants, now denies models, MCP servers and agents instead of leaving the agent key uncapped. The MCP caller ceiling moves to MCPServerManager.get_allowed_mcp_servers so it bounds the full union, allow_all_keys and submitted servers included, on the fallback path too Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .../mcp_server/auth/user_api_key_auth_mcp.py | 54 +++--- .../mcp_server/mcp_server_manager.py | 31 +++- .../agent_endpoints/auth/agent_caller.py | 52 ++++-- .../auth/agent_permission_handler.py | 20 ++- litellm/proxy/auth/auth_checks.py | 42 ++++- .../auth/test_user_api_key_auth_mcp.py | 84 ---------- .../mcp_server/test_mcp_server_manager.py | 157 ++++++++++++++++++ .../agent_endpoints/auth/test_agent_caller.py | 41 ++++- .../auth/test_agent_permission_handler.py | 81 +++++++-- .../proxy/auth/test_auth_checks.py | 40 +++++ 10 files changed, 440 insertions(+), 162 deletions(-) diff --git a/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py b/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py index 2e5cad29b0a..d49fe405c88 100644 --- a/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py +++ b/litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py @@ -1,9 +1,9 @@ import re -from collections.abc import Mapping, Sequence +from collections.abc import Awaitable, Callable, Mapping, Sequence from dataclasses import dataclass from datetime import datetime, timezone from types import MappingProxyType -from typing import TYPE_CHECKING, Final, Literal, cast +from typing import TYPE_CHECKING, Final, Literal, TypeAlias, cast from fastapi import HTTPException from starlette.datastructures import Headers @@ -48,7 +48,7 @@ from litellm.proxy.agent_endpoints.auth.agent_access_groups import ( CeilingResolver, resolve_agent_access_group_ceiling, ) -from litellm.proxy.agent_endpoints.auth.agent_caller import agent_caller_auth +from litellm.proxy.agent_endpoints.auth.agent_caller import agent_caller_auth, agent_caller_resolves from litellm.proxy.auth.ip_address_utils import IPAddressUtils from litellm.proxy.auth.user_api_key_auth import ( _get_bearer_token_or_received_api_key, # pyright: ignore[reportPrivateUsage] # shared x-litellm-api-key parser lives with user_api_key_auth @@ -73,6 +73,7 @@ if TYPE_CHECKING: _EMPTY_TOOLSET_GRANTS: Final[Mapping[str, Sequence[str]]] = MappingProxyType({}) +CallerServersResolver: TypeAlias = Callable[[UserAPIKeyAuth], Awaitable[Sequence[str]]] # mutable-ok: Callable params def _as_list(values: Sequence[str] | None) -> list[str] | None: # mutable-ok: resolver returns a list @@ -1578,21 +1579,14 @@ class MCPRequestHandler: "Applied agent intersection filter. Final allowed servers: %s", allowed_mcp_servers ) - ######################################################### - # Cap an agent key at what the user and team that invoked the agent may reach - ######################################################### - caller_capped, caller_restricts = await MCPRequestHandler._apply_agent_caller_ceiling( - allowed_mcp_servers, user_api_key_auth - ) - ######################################################### # Apply the internal user's own ceiling (the entitlement attached to the human) ######################################################### capped, user_restricts = await MCPRequestHandler._apply_user_server_ceiling( - caller_capped, user_api_key_auth, keyless_source=keyless_source + allowed_mcp_servers, user_api_key_auth, keyless_source=keyless_source ) allowed_mcp_servers = list(capped) - has_lower_level_mcp_restrictions = has_lower_level_mcp_restrictions or caller_restricts or user_restricts + has_lower_level_mcp_restrictions = has_lower_level_mcp_restrictions or user_restricts ######################################################### # Apply org-level ceiling if org_id is set @@ -2936,26 +2930,24 @@ class MCPRequestHandler: return capped, True @staticmethod - async def _apply_agent_caller_ceiling( - allowed_mcp_servers: Sequence[str], - user_api_key_auth: UserAPIKeyAuth | None = None, - ) -> tuple[tuple[str, ...], bool]: - """Narrow an agent key's servers to those the invoking user and team (echoed back by the agent - as ``x-litellm-user-id`` / ``x-litellm-team-id``) may reach: the echoed team's grants when it - names any, then the echoed user's own entitlement. Raises like the user ceiling when that - entitlement is known but unreadable, so the resolver denies rather than widens.""" + async def agent_caller_server_ceiling( + user_api_key_auth: UserAPIKeyAuth | None, + resolve_servers: CallerServersResolver, + ) -> frozenset[str] | None: + """Servers the human who invoked this agent (echoed back as ``x-litellm-user-id`` / + ``x-litellm-team-id``) could reach with a key of their own; None when the key acts for nobody. + An echoed identity the proxy cannot load is an empty ceiling, since the grant resolvers answer + "no grants" for a missing row exactly as for a real one with none.""" caller_auth: Final = agent_caller_auth(user_api_key_auth) if user_api_key_auth else None - if caller_auth is None: - return tuple(allowed_mcp_servers), False - team_servers: Final = frozenset(await MCPRequestHandler._get_allowed_mcp_servers_for_team(caller_auth)) - team_capped: Final = ( - tuple(server for server in allowed_mcp_servers if server in team_servers) - if team_servers - else tuple(allowed_mcp_servers) - ) - user_capped, user_restricts = await MCPRequestHandler._apply_user_server_ceiling(team_capped, caller_auth) - verbose_logger.debug("Applied agent caller ceiling. Final allowed servers: %s", user_capped) - return user_capped, bool(team_servers) or user_restricts + if caller_auth is None or user_api_key_auth is None: + return None + if not await MCPRequestHandler._agent_caller_resolves(user_api_key_auth): + return frozenset() + return frozenset(await resolve_servers(caller_auth)) + + @staticmethod + async def _agent_caller_resolves(user_api_key_auth: UserAPIKeyAuth) -> bool: + return await agent_caller_resolves(user_api_key_auth) @staticmethod async def _user_places_mcp_ceiling(user_api_key_auth: UserAPIKeyAuth | None = None) -> bool: diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py index 4a2713cb19c..d9a85518456 100644 --- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py @@ -3391,6 +3391,9 @@ class MCPServerManager: resolved_general_settings: Final = proxy_general_settings if general_settings is None else general_settings allow_all_server_ids: Final = self.get_allow_all_keys_server_ids() + caller_ceiling: Final = await MCPRequestHandler.agent_caller_server_ceiling( + user_api_key_auth, self.get_allowed_mcp_servers + ) # A keyless admitted subject is resolved per grant source, and channel decisions that are # absolute for a scoped KEY credential are not absolute for it: its own opt-out silences its @@ -3479,19 +3482,31 @@ class MCPServerManager: ) if len(combined_servers) == 0: verbose_logger.debug("No allowed MCP Servers found for user api key auth.") - scope = MCPServerManager._admitted_session_resource_scope(user_api_key_auth) - return [server_id for server_id in combined_servers if scope is None or server_id == scope] + return MCPServerManager._within_ceilings(combined_servers, user_api_key_auth, caller_ceiling) except Exception: # noqa: BLE001 verbose_logger.exception( "Failed to get allowed MCP servers; team-level object_permission " "grants may be dropped. Falling back to global and submitted servers." ) - scope = MCPServerManager._admitted_session_resource_scope(user_api_key_auth) - return [ - server_id - for server_id in dict.fromkeys(allow_all_server_ids + submitted_server_ids) - if scope is None or server_id == scope - ] + return MCPServerManager._within_ceilings( + dict.fromkeys(allow_all_server_ids + submitted_server_ids), user_api_key_auth, caller_ceiling + ) + + @staticmethod + def _within_ceilings( + server_ids: Iterable[str], + user_api_key_auth: UserAPIKeyAuth | None, + caller_ceiling: frozenset[str] | None, + ) -> list[str]: + """Ceilings over the whole reachable set, applied AFTER every union (grants, operator-open, + submitted) and on the fallback path too: the admitted session's resource scope and the + invoking human's own reach when an agent key acts for one.""" + scope: Final = MCPServerManager._admitted_session_resource_scope(user_api_key_auth) + return [ + server_id + for server_id in server_ids + if (scope is None or server_id == scope) and (caller_ceiling is None or server_id in caller_ceiling) + ] async def resolve_toolset_tool_permissions( self, diff --git a/litellm/proxy/agent_endpoints/auth/agent_caller.py b/litellm/proxy/agent_endpoints/auth/agent_caller.py index 47d43e8f71b..5d0918be98b 100644 --- a/litellm/proxy/agent_endpoints/auth/agent_caller.py +++ b/litellm/proxy/agent_endpoints/auth/agent_caller.py @@ -7,8 +7,8 @@ substituted for, the agent key's own grants and the agent's access group ceiling can only narrow access and need no trust. """ -from collections.abc import Mapping -from typing import Final +from collections.abc import Awaitable, Callable, Mapping +from typing import Final, TypeAlias from litellm._logging import verbose_proxy_logger from litellm.proxy._types import LiteLLM_TeamTable, LiteLLM_UserTable, UserAPIKeyAuth @@ -18,6 +18,12 @@ from litellm.types.agents import ( AgentCaller, ) +LoadedCallerTeam: TypeAlias = LiteLLM_TeamTable | None +LoadedCallerUser: TypeAlias = LiteLLM_UserTable | None +CallerTeamLoader: TypeAlias = Callable[[UserAPIKeyAuth], Awaitable[LoadedCallerTeam]] # mutable-ok: Callable params +CallerUserLoader: TypeAlias = Callable[[UserAPIKeyAuth], Awaitable[LoadedCallerUser]] # mutable-ok: Callable params +CallerResolver: TypeAlias = Callable[[UserAPIKeyAuth], Awaitable[bool]] # mutable-ok: Callable params + def _header(headers: Mapping[str, str], name: str) -> str | None: value: Final = next((raw for key, raw in headers.items() if key.lower() == name), None) @@ -51,12 +57,12 @@ def agent_caller_auth(user_api_key_auth: UserAPIKeyAuth) -> UserAPIKeyAuth | Non async def load_agent_caller_team(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_TeamTable | None: """The invoking team's row, or ``None`` when no team id was echoed. Raises when the id names a team that cannot be loaded, since a caller we cannot resolve must not be treated as unrestricted.""" - from litellm.proxy.auth.auth_checks import get_team_object - from litellm.proxy.proxy_server import prisma_client, proxy_logging_obj, user_api_key_cache - caller: Final = user_api_key_auth.agent_caller if caller is None or caller.team_id is None: return None + from litellm.proxy.auth.auth_checks import get_team_object + from litellm.proxy.proxy_server import prisma_client, proxy_logging_obj, user_api_key_cache + return await get_team_object( team_id=caller.team_id, prisma_client=prisma_client, @@ -67,14 +73,15 @@ async def load_agent_caller_team(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_T async def load_agent_caller_user(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_UserTable | None: - """The invoking user's row, or ``None`` when no user id was echoed or the row does not exist.""" - from litellm.proxy.auth.auth_checks import get_user_object - from litellm.proxy.proxy_server import prisma_client, proxy_logging_obj, user_api_key_cache - + """The invoking user's row, or ``None`` when no user id was echoed. Raises ``UserNotFoundError`` when + the id names no user, so an unresolvable caller is denied rather than left uncapped.""" caller: Final = user_api_key_auth.agent_caller if caller is None or caller.user_id is None: return None - user_object: Final = await get_user_object( + from litellm.proxy.auth.auth_checks import get_user_object + from litellm.proxy.proxy_server import prisma_client, proxy_logging_obj, user_api_key_cache + + return await get_user_object( user_id=caller.user_id, prisma_client=prisma_client, user_api_key_cache=user_api_key_cache, @@ -82,6 +89,25 @@ async def load_agent_caller_user(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_U parent_otel_span=user_api_key_auth.parent_otel_span, proxy_logging_obj=proxy_logging_obj, ) - if user_object is None: - verbose_proxy_logger.debug("agent caller user %r not found; no user ceiling applied", caller.user_id) - return user_object + + +async def agent_caller_resolves( + user_api_key_auth: UserAPIKeyAuth, + load_team: CallerTeamLoader = load_agent_caller_team, + load_user: CallerUserLoader = load_agent_caller_user, +) -> bool: + """Whether the echoed ids name a team (when one was echoed, else a user) the proxy can load. The + grant resolvers answer "no grants" for a missing row just as for an unrestricted one, so callers + ask this first and deny outright when the invoking identity cannot be resolved.""" + caller: Final = user_api_key_auth.agent_caller + if caller is None: + return True + try: + if caller.team_id is not None: + await load_team(user_api_key_auth) + else: + await load_user(user_api_key_auth) + except Exception as error: # noqa: BLE001 # any failure to resolve the caller must deny, never widen + verbose_proxy_logger.warning("agent caller %s could not be resolved, denying: %s", caller, error) + return False + return True diff --git a/litellm/proxy/agent_endpoints/auth/agent_permission_handler.py b/litellm/proxy/agent_endpoints/auth/agent_permission_handler.py index 9fe74bfee3f..d54924b0536 100644 --- a/litellm/proxy/agent_endpoints/auth/agent_permission_handler.py +++ b/litellm/proxy/agent_endpoints/auth/agent_permission_handler.py @@ -23,7 +23,11 @@ from litellm.proxy.agent_endpoints.auth.agent_access_groups import ( CeilingResolver, resolve_agent_access_group_ceiling, ) -from litellm.proxy.agent_endpoints.auth.agent_caller import agent_caller_auth +from litellm.proxy.agent_endpoints.auth.agent_caller import ( + CallerResolver, + agent_caller_auth, + agent_caller_resolves, +) from litellm.repositories.table_repositories import AgentsRepository from litellm.types.agents import AgentResponse @@ -83,11 +87,12 @@ class AgentRequestHandler: async def resolve_agent_access( user_api_key_auth: UserAPIKeyAuth | None = None, resolve_ceiling: CeilingResolver = resolve_agent_access_group_ceiling, + caller_resolves: CallerResolver = agent_caller_resolves, ) -> AgentAccess: """Agents the key may reach: key and team grants, intersected with the agent's access group ceiling and, for an agent key acting on behalf of an invoking user, with that user's team grants.""" key_team_access: Final = await AgentRequestHandler._resolve_key_team_agent_access(user_api_key_auth) - caller_access: Final = await AgentRequestHandler._agent_caller_access(user_api_key_auth) + caller_access: Final = await AgentRequestHandler._agent_caller_access(user_api_key_auth, caller_resolves) own_access: Final = _intersect_agent_access(key_team_access, caller_access) agent_ceiling: Final = await AgentRequestHandler._agent_access_group_ceiling(user_api_key_auth, resolve_ceiling) if agent_ceiling is None: @@ -97,10 +102,14 @@ class AgentRequestHandler: return RestrictedAgentAccess(own_access.agent_ids & agent_ceiling) @staticmethod - async def _agent_caller_access(user_api_key_auth: UserAPIKeyAuth | None) -> AgentAccess: + async def _agent_caller_access( + user_api_key_auth: UserAPIKeyAuth | None, caller_resolves: CallerResolver + ) -> AgentAccess: caller_auth: Final = agent_caller_auth(user_api_key_auth) if user_api_key_auth else None - if caller_auth is None: + if caller_auth is None or user_api_key_auth is None: return UnrestrictedAgentAccess() + if not await caller_resolves(user_api_key_auth): + return RestrictedAgentAccess(frozenset()) return await AgentRequestHandler._get_allowed_agents_for_team(caller_auth) @staticmethod @@ -132,6 +141,7 @@ class AgentRequestHandler: agent_id: str, user_api_key_auth: UserAPIKeyAuth | None = None, resolve_ceiling: CeilingResolver = resolve_agent_access_group_ceiling, + caller_resolves: CallerResolver = agent_caller_resolves, ) -> bool: """ Check if a specific agent is allowed for the given user/key. @@ -145,7 +155,7 @@ class AgentRequestHandler: """ from litellm.proxy.agent_endpoints.agent_registry import global_agent_registry - match await AgentRequestHandler.resolve_agent_access(user_api_key_auth, resolve_ceiling): + match await AgentRequestHandler.resolve_agent_access(user_api_key_auth, resolve_ceiling, caller_resolves): case UnrestrictedAgentAccess(): return True case RestrictedAgentAccess(allowed_agent_ids): diff --git a/litellm/proxy/auth/auth_checks.py b/litellm/proxy/auth/auth_checks.py index b3efde7f05f..4d062470b95 100644 --- a/litellm/proxy/auth/auth_checks.py +++ b/litellm/proxy/auth/auth_checks.py @@ -15,7 +15,7 @@ import re import time from collections.abc import Awaitable, Callable, Iterator, Mapping, Sequence from types import MappingProxyType -from typing import TYPE_CHECKING, Any, Final, Literal, Optional, Protocol, TypeAlias +from typing import TYPE_CHECKING, Any, Final, Literal, Optional, Protocol, TypeVar from fastapi import HTTPException, Request, status from pydantic import BaseModel, TypeAdapter @@ -73,6 +73,8 @@ from litellm.proxy.agent_endpoints.auth.agent_access_groups import ( resolve_agent_access_group_ceiling, ) from litellm.proxy.agent_endpoints.auth.agent_caller import ( + CallerTeamLoader, + CallerUserLoader, agent_caller_auth, load_agent_caller_team, load_agent_caller_user, @@ -4365,12 +4367,6 @@ async def _check_agent_access_group_model_access( ) -LoadedCallerTeam: TypeAlias = LiteLLM_TeamTable | None -LoadedCallerUser: TypeAlias = LiteLLM_UserTable | None -CallerTeamLoader: TypeAlias = Callable[[UserAPIKeyAuth], Awaitable[LoadedCallerTeam]] # mutable-ok: Callable params -CallerUserLoader: TypeAlias = Callable[[UserAPIKeyAuth], Awaitable[LoadedCallerUser]] # mutable-ok: Callable params - - async def _check_agent_caller_model_access( model: str | list[str] | None, # mutable-ok: the model checks it delegates to take list[str] valid_token: UserAPIKeyAuth | None, @@ -4388,7 +4384,9 @@ async def _check_agent_caller_model_access( caller_auth: Final = agent_caller_auth(valid_token) if caller_auth is None: return - caller_team: Final = await load_team(valid_token) + caller_team: Final = await _load_agent_caller_row_or_deny( + load_team, valid_token, model, ProxyErrorTypes.team_model_access_denied + ) if caller_team is not None: await can_team_access_model( model=model, @@ -4406,12 +4404,38 @@ async def _check_agent_caller_model_access( proxy_logging_obj=proxy_logging_obj, ) return - caller_user: Final = await load_user(valid_token) + caller_user: Final = await _load_agent_caller_row_or_deny( + load_user, valid_token, model, ProxyErrorTypes.user_model_access_denied + ) if caller_user is None: return await can_user_call_model(model=model, llm_router=llm_router, user_object=caller_user) +CallerRowT = TypeVar("CallerRowT", LiteLLM_TeamTable | None, LiteLLM_UserTable | None) + + +async def _load_agent_caller_row_or_deny( + load: Callable[[UserAPIKeyAuth], Awaitable[CallerRowT]], + valid_token: UserAPIKeyAuth, + model: str | list[str], # mutable-ok: mirrors the model checks this denial stands in for + error_type: ProxyErrorTypes, +) -> CallerRowT: + """An echoed caller id that names no row (or cannot be read) denies the model outright, since an + invoking identity we cannot resolve must never leave the agent key uncapped.""" + try: + return await load(valid_token) + except Exception as error: # noqa: BLE001 # any failure to resolve the invoking identity must deny + caller: Final = valid_token.agent_caller + raise ModelAccessDeniedProxyException( + message=model_access_denied_client_message(model=model), + internal_message=f"Agent caller could not be resolved. Caller={caller}, Model={model}. Error={error}", + type=error_type, + param="model", + code=status.HTTP_403_FORBIDDEN, + ) from error + + def _model_in_team_aliases(model: str, team_model_aliases: dict[str, str] | None = None) -> bool: """ Returns True if `model` being accessed is an alias of a team model diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py b/tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py index 5c885a3168d..e3ef3d1babf 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py @@ -22,7 +22,6 @@ from litellm.proxy._types import ( SpecialMCPServerNames, UserAPIKeyAuth, ) -from litellm.types.agents import AgentCaller @pytest.mark.asyncio @@ -4196,89 +4195,6 @@ def test_agent_capped_servers_without_agent_restrictions_is_uncapped(): class TestAgentMCPPermissions: """Test agent-level MCP server and tool permission intersection.""" - @staticmethod - def _agent_key_acting_for(user_id: str, team_id: str | None) -> UserAPIKeyAuth: - agent_key = UserAPIKeyAuth(api_key="agent-key", user_id="agent-owner", team_id="agent-team", agent_id="agent-1") - agent_key.agent_caller = AgentCaller(user_id=user_id, team_id=team_id) - return agent_key - - @staticmethod - def _team_servers(grants: dict[str, list[str]]) -> AsyncMock: - async def by_team(user_api_key_auth: UserAPIKeyAuth | None = None) -> list[str]: - assert user_api_key_auth is not None - return grants.get(user_api_key_auth.team_id or "", []) - - return AsyncMock(side_effect=by_team) - - @staticmethod - def _user_servers(grants: dict[str, list[str] | None]) -> AsyncMock: - async def by_user(user_api_key_auth: UserAPIKeyAuth | None = None) -> list[str] | None: - assert user_api_key_auth is not None - return grants.get(user_api_key_auth.user_id or "", []) - - return AsyncMock(side_effect=by_user) - - async def test_agent_key_acting_for_a_user_is_capped_at_the_invoking_teams_servers(self): - """LIT-8014: the agent's own key reaches server_1 and server_2, but the human who invoked it - belongs to a team granted only server_2, so on their behalf the agent reaches only server_2.""" - agent_key = self._agent_key_acting_for(user_id="alice", team_id="callers") - - with ( - patch.object( # test-quality-ok: the level resolvers read proxy_server globals with no injection seam - MCPRequestHandler, "_get_allowed_mcp_servers_for_key", AsyncMock(return_value=["server_1", "server_2"]) - ), - patch.object( # test-quality-ok: same seam, keyed by which team is being asked about - MCPRequestHandler, - "_get_allowed_mcp_servers_for_team", - self._team_servers({"callers": ["server_2", "server_3"]}), - ), - patch.object( # test-quality-ok: agent object_permission lookup hits the DB, not under test here - MCPRequestHandler, "_get_allowed_mcp_servers_for_agent", AsyncMock(return_value=[]) - ), - patch.object( # test-quality-ok: neither the agent's owner nor the caller has a personal grant - MCPRequestHandler, "_get_allowed_mcp_servers_for_user", self._user_servers({}) - ), - ): - assert await MCPRequestHandler.get_allowed_mcp_servers(user_api_key_auth=agent_key) == ["server_2"] - - async def test_agent_key_acting_for_a_teamless_user_is_capped_at_that_users_servers(self): - agent_key = self._agent_key_acting_for(user_id="alice", team_id=None) - - with ( - patch.object( # test-quality-ok: the level resolvers read proxy_server globals with no injection seam - MCPRequestHandler, "_get_allowed_mcp_servers_for_key", AsyncMock(return_value=["server_1", "server_2"]) - ), - patch.object( # test-quality-ok: same seam - MCPRequestHandler, "_get_allowed_mcp_servers_for_team", self._team_servers({}) - ), - patch.object( # test-quality-ok: agent object_permission lookup hits the DB, not under test here - MCPRequestHandler, "_get_allowed_mcp_servers_for_agent", AsyncMock(return_value=[]) - ), - patch.object( # test-quality-ok: same seam, keyed by which user is being asked about - MCPRequestHandler, "_get_allowed_mcp_servers_for_user", self._user_servers({"alice": ["server_1"]}) - ), - ): - assert await MCPRequestHandler.get_allowed_mcp_servers(user_api_key_auth=agent_key) == ["server_1"] - - async def test_agent_key_acting_for_a_caller_whose_entitlement_is_unreadable_reaches_nothing(self): - agent_key = self._agent_key_acting_for(user_id="alice", team_id=None) - - with ( - patch.object( # test-quality-ok: the level resolvers read proxy_server globals with no injection seam - MCPRequestHandler, "_get_allowed_mcp_servers_for_key", AsyncMock(return_value=["server_1"]) - ), - patch.object( # test-quality-ok: same seam - MCPRequestHandler, "_get_allowed_mcp_servers_for_team", self._team_servers({}) - ), - patch.object( # test-quality-ok: agent object_permission lookup hits the DB, not under test here - MCPRequestHandler, "_get_allowed_mcp_servers_for_agent", AsyncMock(return_value=[]) - ), - patch.object( # test-quality-ok: None is the resolver's own "entitlement unresolvable" signal - MCPRequestHandler, "_get_allowed_mcp_servers_for_user", self._user_servers({"alice": None}) - ), - ): - assert await MCPRequestHandler.get_allowed_mcp_servers(user_api_key_auth=agent_key) == [] - async def test_get_allowed_mcp_servers_agent_intersection(self): """Key/team allow [server_1, server_2]; agent allows [server_1]. Result = [server_1].""" user_api_key_auth = UserAPIKeyAuth( diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py index 9f42a523350..f6b76cd96b4 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py @@ -11903,6 +11903,163 @@ class TestSessionResourceScopeIntersect: assert fallback == ["granted-id"] +class TestAgentCallerServerCeiling: + """LIT-8014: an agent key that echoes the invoking human's ``x-litellm-user-id`` / + ``x-litellm-team-id`` reaches only what that human could reach with a key of their own, + applied over the agent key's full union so operator-open servers do not slip past it.""" + + @staticmethod + def _agent_key_acting_for(user_id: str | None, team_id: str | None) -> UserAPIKeyAuth: + from litellm.types.agents import AgentCaller + + agent_key: Final = UserAPIKeyAuth(api_key="agent-key", user_id="agent-owner", agent_id="agent-1") + agent_key.agent_caller = AgentCaller(user_id=user_id, team_id=team_id) + return agent_key + + @staticmethod + def _access_by_principal(grants: dict[str, tuple[str, ...]]) -> AsyncMock: + """Server grants keyed by principal: the agent key (``agent_id`` set) resolves under the key + ``"agent"``; the synthetic caller the ceiling asks about resolves under its team, else user.""" + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPServerAccess + + async def resolve(user_api_key_auth: UserAPIKeyAuth | None = None, **_: object) -> MCPServerAccess: + assert user_api_key_auth is not None + principal: Final = ( + "agent" if user_api_key_auth.agent_id else user_api_key_auth.team_id or user_api_key_auth.user_id + ) + return MCPServerAccess(server_ids=grants[principal]) + + return AsyncMock(side_effect=resolve) + + @staticmethod + def _known_callers(team_ids: frozenset[str], user_ids: frozenset[str]) -> AsyncMock: + async def resolves(user_api_key_auth: UserAPIKeyAuth) -> bool: + caller: Final = user_api_key_auth.agent_caller + if caller is None: + return True + if caller.team_id is not None: + return caller.team_id in team_ids + return caller.user_id in user_ids + + return AsyncMock(side_effect=resolves) + + @contextlib.contextmanager + def _resolvers( + self, + grants: dict[str, tuple[str, ...]], + known_teams: frozenset[str] = frozenset(), + known_users: frozenset[str] = frozenset(), + allow_all: tuple[str, ...] = ("public",), + ): + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPRequestHandler + + with ( + patch.object(MCPServerManager, "get_allow_all_keys_server_ids", return_value=list(allow_all)), + patch.object( + MCPServerManager, + "_get_active_submitted_mcp_server_ids_for_user", + new_callable=AsyncMock, + return_value=[], + ), + patch.object( # test-quality-ok: the level resolvers read proxy_server globals with no injection seam + MCPRequestHandler, "get_mcp_server_access", self._access_by_principal(grants) + ), + patch.object( # test-quality-ok: caller row lookup hits the DB, not under test here + MCPRequestHandler, "_agent_caller_resolves", self._known_callers(known_teams, known_users) + ), + ): + yield MCPServerManager() + + @pytest.mark.asyncio + async def test_agent_key_acting_for_a_user_is_capped_at_the_invoking_teams_servers(self): + agent_key: Final = self._agent_key_acting_for(user_id="alice", team_id="callers") + with self._resolvers( + {"agent": ("server_1", "server_2"), "callers": ("server_2", "server_3")}, known_teams=frozenset({"callers"}) + ) as manager: + assert set(await manager.get_allowed_mcp_servers(agent_key)) == {"server_2", "public"} + + @pytest.mark.asyncio + async def test_agent_key_acting_for_a_teamless_user_is_capped_at_that_users_servers(self): + agent_key: Final = self._agent_key_acting_for(user_id="alice", team_id=None) + with self._resolvers( + {"agent": ("server_1", "server_2"), "alice": ("server_1",)}, known_users=frozenset({"alice"}) + ) as manager: + assert set(await manager.get_allowed_mcp_servers(agent_key)) == {"server_1", "public"} + + @pytest.mark.asyncio + async def test_public_server_is_capped_when_the_invoking_team_cannot_reach_it(self): + """The cap applies AFTER the allow_all_keys union: a public server the caller's own union + would not contain (a scoped caller under mcp_allow_all_keys_respects_mcp_scope, here modelled + by the caller resolving to no public server) stays out of the agent's reach on their behalf.""" + agent_key: Final = self._agent_key_acting_for(user_id="alice", team_id="callers") + with ( + self._resolvers({"agent": ("server_1",), "callers": ("server_1",)}, known_teams=frozenset({"callers"})), + patch.object( + MCPServerManager, + "operator_open_server_ids", + new_callable=AsyncMock, + side_effect=lambda auth, **_: set() if auth.agent_id is None else {"public"}, + ), + ): + assert await MCPServerManager().get_allowed_mcp_servers(agent_key) == ["server_1"] + + @pytest.mark.asyncio + async def test_agent_key_acting_for_a_team_with_no_grants_reaches_only_what_that_team_can(self): + agent_key: Final = self._agent_key_acting_for(user_id="alice", team_id="callers") + with self._resolvers( + {"agent": ("server_1", "server_2"), "callers": ()}, known_teams=frozenset({"callers"}) + ) as manager: + assert await manager.get_allowed_mcp_servers(agent_key) == ["public"] + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("user_id", "team_id"), + [("alice", "ghost-team"), ("ghost", None)], + ids=["unknown_team", "unknown_teamless_user"], + ) + async def test_agent_key_acting_for_an_unresolvable_caller_reaches_nothing(self, user_id: str, team_id: str | None): + """An echoed identity the proxy cannot load is an empty ceiling: not even public servers.""" + agent_key: Final = self._agent_key_acting_for(user_id=user_id, team_id=team_id) + with self._resolvers( + {"agent": ("server_1", "server_2")}, known_teams=frozenset({"callers"}), known_users=frozenset({"alice"}) + ) as manager: + assert await manager.get_allowed_mcp_servers(agent_key) == [] + + @pytest.mark.asyncio + async def test_resolver_fault_never_widens_a_delegated_agent_past_the_caller(self): + """The exception fallback (allow_all + submitted) is bounded by the caller ceiling too.""" + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPRequestHandler + + agent_key: Final = self._agent_key_acting_for(user_id="alice", team_id="callers") + + async def faulting_for_agent(user_api_key_auth: UserAPIKeyAuth | None = None, **_: object): + from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import MCPServerAccess + + assert user_api_key_auth is not None + if user_api_key_auth.agent_id: + raise RuntimeError("resolver down") + return MCPServerAccess(server_ids=("server_1",)) + + with ( + self._resolvers({}, known_teams=frozenset({"callers"})), + patch.object(MCPRequestHandler, "get_mcp_server_access", AsyncMock(side_effect=faulting_for_agent)), + patch.object( + MCPServerManager, + "operator_open_server_ids", + new_callable=AsyncMock, + side_effect=lambda auth, **_: set() if auth.agent_id is None else {"public"}, + ), + ): + assert await MCPServerManager().get_allowed_mcp_servers(agent_key) == [] + + @pytest.mark.asyncio + async def test_caller_headers_do_not_cap_a_key_that_is_not_an_agent(self): + plain_key: Final = UserAPIKeyAuth(api_key="sk-plain", user_id="alice") + assert plain_key.agent_caller is None + with self._resolvers({"alice": ("server_1", "server_2")}) as manager: + assert set(await manager.get_allowed_mcp_servers(plain_key)) == {"server_1", "server_2", "public"} + + class TestClientForwardedDiscoveryFailureIsNotFatal: """A failed OAuth metadata discovery may only brick the flows the gateway runs itself. diff --git a/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_caller.py b/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_caller.py index b08964503c8..d938a2c1806 100644 --- a/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_caller.py +++ b/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_caller.py @@ -2,8 +2,12 @@ from typing import Final import pytest -from litellm.proxy._types import UserAPIKeyAuth -from litellm.proxy.agent_endpoints.auth.agent_caller import agent_caller_auth, agent_caller_from_headers +from litellm.proxy._types import LiteLLM_TeamTable, LiteLLM_UserTable, UserAPIKeyAuth +from litellm.proxy.agent_endpoints.auth.agent_caller import ( + agent_caller_auth, + agent_caller_from_headers, + agent_caller_resolves, +) from litellm.types.agents import AgentCaller _AGENT_KEY: Final = UserAPIKeyAuth(api_key="agent-key", user_id="agent-owner", team_id="agent-team", agent_id="agent-1") @@ -55,3 +59,36 @@ def test_agent_caller_cannot_be_set_from_a_request_payload() -> None: assert forged.agent_caller is None assert "agent_caller" not in forged.model_dump() + + +async def _team_row(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_TeamTable | None: + return LiteLLM_TeamTable(team_id="callers") + + +async def _user_row(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_UserTable | None: + return LiteLLM_UserTable(user_id="alice", max_budget=None, user_email=None) + + +async def _no_row(user_api_key_auth: UserAPIKeyAuth) -> None: + raise ValueError("doesn't exist in db") + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("caller", "load_team", "load_user", "expected"), + [ + (None, _no_row, _no_row, True), + (AgentCaller(user_id="alice", team_id="callers"), _team_row, _no_row, True), + (AgentCaller(user_id="alice", team_id="ghost-team"), _no_row, _user_row, False), + (AgentCaller(user_id="alice", team_id=None), _no_row, _user_row, True), + (AgentCaller(user_id="ghost", team_id=None), _team_row, _no_row, False), + ], + ids=["no_caller", "known_team", "unknown_team_despite_known_user", "known_user", "unknown_user"], +) +async def test_caller_resolves_only_when_the_echoed_team_or_else_user_names_a_row( + caller: AgentCaller | None, load_team, load_user, expected: bool +) -> None: + agent_key: Final = UserAPIKeyAuth(agent_id="agent-1") + agent_key.agent_caller = caller + + assert await agent_caller_resolves(agent_key, load_team=load_team, load_user=load_user) is expected diff --git a/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_permission_handler.py b/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_permission_handler.py index a87716375e8..fe00607f403 100644 --- a/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_permission_handler.py +++ b/tests/test_litellm/proxy/agent_endpoints/auth/test_agent_permission_handler.py @@ -10,9 +10,10 @@ from unittest.mock import AsyncMock, patch import pytest from litellm.constants import UI_SESSION_TOKEN_TEAM_ID -from litellm.proxy._types import LiteLLM_ObjectPermissionTable, LitellmUserRoles, UserAPIKeyAuth +from litellm.proxy._types import LiteLLM_ObjectPermissionTable, LiteLLM_TeamTable, LitellmUserRoles, UserAPIKeyAuth from litellm.proxy.agent_endpoints.agent_registry import AgentRegistry from litellm.proxy.agent_endpoints.auth.agent_access_groups import AgentAccessGroupCeiling, CeilingResolver +from litellm.proxy.agent_endpoints.auth.agent_caller import CallerResolver, agent_caller_resolves from litellm.proxy.agent_endpoints.auth.agent_permission_handler import ( AgentAccess, AgentRequestHandler, @@ -204,6 +205,24 @@ class TestAgentRequestHandler: return AsyncMock(side_effect=by_team) + @staticmethod + def _known_teams(team_ids: frozenset[str]) -> CallerResolver: + """The real caller resolver over a team loader that behaves like ``get_team_object``: a row for + a known id, an error for an unknown one.""" + + async def load(user_api_key_auth: UserAPIKeyAuth) -> LiteLLM_TeamTable | None: + caller: Final = user_api_key_auth.agent_caller + if caller is None or caller.team_id is None: + return None + if caller.team_id not in team_ids: + raise ValueError(f"Team doesn't exist in db. Team={caller.team_id}") + return LiteLLM_TeamTable(team_id=caller.team_id) + + async def resolves(user_api_key_auth: UserAPIKeyAuth) -> bool: + return await agent_caller_resolves(user_api_key_auth, load_team=load) + + return resolves + async def test_agent_key_acting_for_a_user_is_capped_at_the_invoking_teams_agents(self): """LIT-8014: the agent's key and access groups reach alpha and beta, but the human who invoked it belongs to a team granted only beta, so on their behalf the agent reaches only beta.""" @@ -216,13 +235,55 @@ class TestAgentRequestHandler: "_get_allowed_agents_for_team", self._team_grants({"callers": RestrictedAgentAccess(frozenset({"agent-beta", "agent-gamma"}))}), ) as mock_team: - assert await AgentRequestHandler.resolve_agent_access(agent_key, resolve) == RestrictedAgentAccess( - frozenset({"agent-beta"}) + assert await AgentRequestHandler.resolve_agent_access( + agent_key, resolve, self._known_teams(frozenset({"callers"})) + ) == RestrictedAgentAccess(frozenset({"agent-beta"})) + assert ( + await AgentRequestHandler.is_agent_allowed( + "agent-alpha", agent_key, resolve, self._known_teams(frozenset({"callers"})) + ) + is False ) - assert await AgentRequestHandler.is_agent_allowed("agent-alpha", agent_key, resolve) is False assert {call.args[0].team_id for call in mock_team.call_args_list} == {None, "callers"} + async def test_agent_key_acting_for_an_unknown_team_reaches_no_agent(self): + """An echoed team id that names no team must deny, not pass as a team with no grants: the + team resolver alone cannot tell the two apart.""" + agent_key: Final = self._key_granting(["agent-alpha"], agent_id="caller-agent") + agent_key.agent_caller = AgentCaller(user_id="alice", team_id="no-such-team") + resolve, _ = self._ceiling_resolver(None) + + with patch.object( # test-quality-ok: the team resolver reads proxy_server globals with no injection seam + AgentRequestHandler, "_get_allowed_agents_for_team", self._team_grants({}) + ) as mock_team: + assert await AgentRequestHandler.resolve_agent_access( + agent_key, resolve, self._known_teams(frozenset({"callers"})) + ) == RestrictedAgentAccess(frozenset()) + assert ( + await AgentRequestHandler.is_agent_allowed( + "agent-alpha", agent_key, resolve, self._known_teams(frozenset({"callers"})) + ) + is False + ) + + assert all(call.args[0].team_id is None for call in mock_team.call_args_list), "unknown team was resolved" + + async def test_agent_key_acting_for_an_unknown_teamless_user_reaches_no_agent(self): + agent_key: Final = self._key_granting(["agent-alpha"], agent_id="caller-agent") + agent_key.agent_caller = AgentCaller(user_id="nobody", team_id=None) + resolve, _ = self._ceiling_resolver(None) + + async def nobody_resolves(user_api_key_auth: UserAPIKeyAuth) -> bool: + return False + + with patch.object( # test-quality-ok: the team resolver reads proxy_server globals with no injection seam + AgentRequestHandler, "_get_allowed_agents_for_team", self._team_grants({}) + ): + assert await AgentRequestHandler.resolve_agent_access( + agent_key, resolve, nobody_resolves + ) == RestrictedAgentAccess(frozenset()) + async def test_agent_key_acting_for_a_user_whose_team_grants_no_agent_reaches_none(self): agent_key: Final = UserAPIKeyAuth(api_key="test-key", user_id="test-user", agent_id="caller-agent") agent_key.agent_caller = AgentCaller(user_id="alice", team_id="callers") @@ -233,9 +294,9 @@ class TestAgentRequestHandler: "_get_allowed_agents_for_team", self._team_grants({"callers": RestrictedAgentAccess(frozenset())}), ): - assert await AgentRequestHandler.resolve_agent_access(agent_key, resolve) == RestrictedAgentAccess( - frozenset() - ) + assert await AgentRequestHandler.resolve_agent_access( + agent_key, resolve, self._known_teams(frozenset({"callers"})) + ) == RestrictedAgentAccess(frozenset()) async def test_agent_key_acting_for_an_ungranted_caller_keeps_its_own_agents(self): agent_key: Final = self._key_granting(["agent-alpha"], agent_id="caller-agent") @@ -245,9 +306,9 @@ class TestAgentRequestHandler: with patch.object( # test-quality-ok: the team resolver reads proxy_server globals with no injection seam AgentRequestHandler, "_get_allowed_agents_for_team", self._team_grants({}) ): - assert await AgentRequestHandler.resolve_agent_access(agent_key, resolve) == RestrictedAgentAccess( - frozenset({"agent-alpha"}) - ) + assert await AgentRequestHandler.resolve_agent_access( + agent_key, resolve, self._known_teams(frozenset({"callers"})) + ) == RestrictedAgentAccess(frozenset({"agent-alpha"})) async def test_agent_access_groups_intersect_with_key_grants(self): diff --git a/tests/test_litellm/proxy/auth/test_auth_checks.py b/tests/test_litellm/proxy/auth/test_auth_checks.py index 0cab6535f3d..4d95fcc0ca2 100644 --- a/tests/test_litellm/proxy/auth/test_auth_checks.py +++ b/tests/test_litellm/proxy/auth/test_auth_checks.py @@ -9261,6 +9261,46 @@ async def test_agent_key_acting_for_a_teamless_user_is_capped_at_that_users_mode assert asked == ["team:None", "user:alice", "team:None", "user:alice"] +_CALLER_LOOKUP_MISS: Final = ProxyException(message="not in db", type="auth_error", param=None, code=404) + + +async def _no_such_team(valid_token: UserAPIKeyAuth) -> LiteLLM_TeamTable | None: + raise _CALLER_LOOKUP_MISS + + +async def _no_such_user(valid_token: UserAPIKeyAuth) -> LiteLLM_UserTable | None: + raise _CALLER_LOOKUP_MISS + + +@pytest.mark.asyncio +async def test_agent_key_acting_for_an_unknown_team_is_denied_with_403(): + """An echoed team id that names no team must deny the agent's own model as a 403 access denial, + never pass uncapped and never surface the lookup's own 404.""" + agent_key: Final = _agent_key_acting_for(user_id="alice", team_id="no-such-team") + _, load_user, asked = _caller_loaders(None, None) + + with pytest.raises(ModelAccessDeniedProxyException) as exc_info: + await _check_caller_models(agent_key, "gpt-5", _no_such_team, load_user) + + assert exc_info.value.type == ProxyErrorTypes.team_model_access_denied + assert exc_info.value.code == str(status.HTTP_403_FORBIDDEN) + assert "team_id='no-such-team'" in exc_info.value.internal_message + assert asked == [], "user lookup must not run once the team lookup failed" + + +@pytest.mark.asyncio +async def test_agent_key_acting_for_an_unknown_teamless_user_is_denied_with_403(): + agent_key: Final = _agent_key_acting_for(user_id="nobody", team_id=None) + load_team, _, _ = _caller_loaders(None, None) + + with pytest.raises(ModelAccessDeniedProxyException) as exc_info: + await _check_caller_models(agent_key, "gpt-5", load_team, _no_such_user) + + assert exc_info.value.type == ProxyErrorTypes.user_model_access_denied + assert exc_info.value.code == str(status.HTTP_403_FORBIDDEN) + assert "user_id='nobody'" in exc_info.value.internal_message + + @pytest.mark.asyncio async def test_agent_key_without_an_echoed_caller_keeps_its_own_models(): agent_key: Final = UserAPIKeyAuth(token="agent-token", agent_id="agent-1", models=["gpt-5", "claude-sonnet"])