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>
This commit is contained in:
yassin 2026-09-22 00:39:25 +00:00
parent cc9970efbf
commit e7f1f0197b
10 changed files with 440 additions and 162 deletions

View file

@ -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:

View file

@ -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,

View file

@ -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

View file

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

View file

@ -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

View file

@ -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(

View file

@ -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.

View file

@ -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

View file

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

View file

@ -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"])