From 0b3461a17c664eecc40982d6f17e83a3b36f8943 Mon Sep 17 00:00:00 2001 From: AUTHENSOR <250658088+AUTHENSOR@users.noreply.github.com> Date: Sat, 5 Sep 2026 18:57:51 -0700 Subject: [PATCH 1/3] fix(proxy): re-check key/team model allowlists on server-side fallbacks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fallback routes swapped kwargs['model'] without re-running can_key_call_model or the team allowlist, so a key restricted to model-a could reach model-b (shared deployments) by triggering the primary's failure (e.g. ContextWindowExceededError). Mirrors the existing budget_fallbacks re-check, which already documents that fallbacks 'cannot bypass model authorization'. Regression: restricted key 403s direct + body-fallback; context-window fallback previously served model-b with 200 — fixed by this change. --- litellm/proxy/common_request_processing.py | 63 ++++++++++++++++- .../router_utils/fallback_event_handlers.py | 68 +++++++++++++++++++ 2 files changed, 130 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/common_request_processing.py b/litellm/proxy/common_request_processing.py index 5e6c9b34332..bb7891f199a 100644 --- a/litellm/proxy/common_request_processing.py +++ b/litellm/proxy/common_request_processing.py @@ -1528,6 +1528,55 @@ def _timing_values( return getattr(logging_obj, "response_timing_metrics", None) or {} # mutable-ok: empty fallback +async def _filter_fallback_models_by_key_access( + fallback_models: Sequence[object], + user_api_key_dict: UserAPIKeyAuth, + llm_router: Router, +) -> Sequence[object]: + """ + Drop fallback targets the key/team is not allowed to call. + + The rate-limit pre-call fallback swaps the request model after auth already + ran for the original model. Without this filter, a key restricted to one + model group would be rerouted to any model group the config (or the key's + router_settings) lists as a fallback. Mirrors the client-side fallback + checks in _enforce_key_and_fallback_model_access. + """ + from litellm.proxy._types import ProxyException + from litellm.proxy.auth.auth_checks import ( # pyright: ignore[reportPrivateUsage] # auth_checks exposes no public pair; budget blocks adding one + _can_object_call_model, + can_key_call_model, + ) + + allowed: list[object] = [] # mutable-ok: builds the filtered fallback list this function returns + for fallback_model in fallback_models: + if not isinstance(fallback_model, str): + # dict-form fallback entries ({model, messages}) re-run auth below + # via common_processing_pre_call_logic's model extraction; keep them. + allowed.append(fallback_model) + continue + try: + await can_key_call_model( + model=fallback_model, + llm_model_list=None, + valid_token=user_api_key_dict, + llm_router=llm_router, + ) + if user_api_key_dict.team_models: + _can_object_call_model( + model=fallback_model, + llm_router=llm_router, + models=user_api_key_dict.team_models, + team_model_aliases=user_api_key_dict.team_model_aliases, + team_id=user_api_key_dict.team_id, + object_type="team", + ) + except ProxyException: + continue + allowed.append(fallback_model) + return allowed + + class ProxyBaseLLMRequestProcessing: def __init__(self, data: dict): self.data = data @@ -2083,8 +2132,20 @@ class ProxyBaseLLMRequestProcessing: fallback_models, ) + # Re-run the key/team model allowlist for each fallback target. + # Auth already ran for the original model; swapping the model here + # must not widen access to model groups the key is denied. Mirrors + # the client-side fallback checks in _enforce_key_and_fallback_model_access. + allowed_fallback_models: Final = await _filter_fallback_models_by_key_access( + fallback_models=fallback_models, + user_api_key_dict=user_api_key_dict, + llm_router=llm_router, + ) + if not allowed_fallback_models: + raise + try: - for fallback_model in fallback_models: + for fallback_model in allowed_fallback_models: if fallback_model == original_model: continue self.data["model"] = fallback_model diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py index 7fda5d96fb0..f1d0c372743 100644 --- a/litellm/router_utils/fallback_event_handlers.py +++ b/litellm/router_utils/fallback_event_handlers.py @@ -446,6 +446,68 @@ def creates_provider_scoped_resource(kwargs: Mapping[str, object]) -> bool: return getattr(kwargs.get("original_function"), "__name__", None) in PROVIDER_SCOPED_CREATION_FUNCTION_NAMES +async def _proxy_key_allows_fallback_model( + litellm_router: LitellmRouter, + kwargs: Mapping[str, object], + fallback_entry: str | Mapping[str, object], +) -> bool: + """ + Re-run the proxy's key/team model allowlist for a server-side fallback target. + + Proxy requests carry the authenticated ``UserAPIKeyAuth`` on their metadata + (``user_api_key_auth``, set in ``add_user_api_key_auth_to_request_metadata``). + The allowlist is enforced at auth time for the request's primary model and + for client-supplied fallbacks in the request body, but a router-configured + fallback swaps the model after auth already ran -- without this check a key + restricted to one model group would be served by any shared deployment the + config lists as a fallback for it. Mirrors the budget_fallbacks re-check in + ``_check_key_model_budget_with_fallback``. Non-proxy (SDK) callers carry no + auth object and are unaffected. + """ + metadata: Final = kwargs.get("metadata") + if not isinstance(metadata, Mapping): + return True + auth: Final = metadata.get("user_api_key_auth") + if auth is None: + return True + model: Final = _get_fallback_target_model_group(fallback_entry) + if model is None: + return True + + # Inline import: the proxy layer is only reachable when the proxy populated + # the metadata above, and a module-level import would be circular. + from litellm.proxy._types import ProxyException + from litellm.proxy.auth.auth_checks import ( # pyright: ignore[reportPrivateUsage] # auth_checks exposes no public pair; budget blocks adding one + _can_object_call_model, + can_key_call_model, + ) + + try: + await can_key_call_model( + model=model, + llm_model_list=None, + valid_token=auth, + llm_router=litellm_router, + ) + team_models: Final = getattr(auth, "team_models", None) + if team_models: + _can_object_call_model( + model=model, + llm_router=litellm_router, + models=team_models, + team_model_aliases=getattr(auth, "team_model_aliases", None), + team_id=getattr(auth, "team_id", None), + object_type="team", + ) + except ProxyException: + verbose_router_logger.info( + "Skipping fallback to model_group = %s: not allowed for this key/team.", + mask_sensitive_structure(model), + ) + return False + return True + + async def run_async_fallback( *args: object, litellm_router: LitellmRouter, @@ -529,6 +591,12 @@ async def run_async_fallback( continue attempted.record(attempt_key) try: + if not await _proxy_key_allows_fallback_model( + litellm_router=litellm_router, + kwargs=kwargs, + fallback_entry=mg, + ): + continue # LOGGING kwargs = litellm_router.log_retry(kwargs=kwargs, e=original_exception) verbose_router_logger.info("Falling back to model_group = %s", mask_sensitive_structure(mg)) From f0f2896264aa60835f79b58105476941edc06a0e Mon Sep 17 00:00:00 2001 From: AUTHENSOR <250658088+AUTHENSOR@users.noreply.github.com> Date: Sun, 20 Sep 2026 03:01:37 -0700 Subject: [PATCH 2/3] address review: use can_key_call_resolved_model for full scope coverage Replaces the separate key + team allowlist checks with the full resolved-model authorization path (can_key_call_resolved_model), which also enforces per-team-member and project model scopes. Also resolves the auth object from both metadata and litellm_metadata buckets, covering /v1/messages and /v1/responses routes that store user_api_key_auth under litellm_metadata. Co-authored-by: veria-ai[bot] --- litellm/proxy/common_request_processing.py | 27 +++-------- .../router_utils/fallback_event_handlers.py | 45 +++++++------------ 2 files changed, 23 insertions(+), 49 deletions(-) diff --git a/litellm/proxy/common_request_processing.py b/litellm/proxy/common_request_processing.py index bb7891f199a..828ca665277 100644 --- a/litellm/proxy/common_request_processing.py +++ b/litellm/proxy/common_request_processing.py @@ -1534,19 +1534,15 @@ async def _filter_fallback_models_by_key_access( llm_router: Router, ) -> Sequence[object]: """ - Drop fallback targets the key/team is not allowed to call. + Drop fallback targets the key is not allowed to call. - The rate-limit pre-call fallback swaps the request model after auth already - ran for the original model. Without this filter, a key restricted to one - model group would be rerouted to any model group the config (or the key's - router_settings) lists as a fallback. Mirrors the client-side fallback - checks in _enforce_key_and_fallback_model_access. + The rate-limit pre-call fallback swaps the request model after auth + already ran for the original model. Without this filter, a key restricted + to one model group would be rerouted to any model group the config (or + the key's router_settings) lists as a fallback. """ from litellm.proxy._types import ProxyException - from litellm.proxy.auth.auth_checks import ( # pyright: ignore[reportPrivateUsage] # auth_checks exposes no public pair; budget blocks adding one - _can_object_call_model, - can_key_call_model, - ) + from litellm.proxy.auth.auth_checks import can_key_call_resolved_model allowed: list[object] = [] # mutable-ok: builds the filtered fallback list this function returns for fallback_model in fallback_models: @@ -1556,21 +1552,12 @@ async def _filter_fallback_models_by_key_access( allowed.append(fallback_model) continue try: - await can_key_call_model( + await can_key_call_resolved_model( model=fallback_model, llm_model_list=None, valid_token=user_api_key_dict, llm_router=llm_router, ) - if user_api_key_dict.team_models: - _can_object_call_model( - model=fallback_model, - llm_router=llm_router, - models=user_api_key_dict.team_models, - team_model_aliases=user_api_key_dict.team_model_aliases, - team_id=user_api_key_dict.team_id, - object_type="team", - ) except ProxyException: continue allowed.append(fallback_model) diff --git a/litellm/router_utils/fallback_event_handlers.py b/litellm/router_utils/fallback_event_handlers.py index f1d0c372743..c3494fed930 100644 --- a/litellm/router_utils/fallback_event_handlers.py +++ b/litellm/router_utils/fallback_event_handlers.py @@ -452,22 +452,22 @@ async def _proxy_key_allows_fallback_model( fallback_entry: str | Mapping[str, object], ) -> bool: """ - Re-run the proxy's key/team model allowlist for a server-side fallback target. + Re-run the proxy's model authorization for a server-side fallback target. - Proxy requests carry the authenticated ``UserAPIKeyAuth`` on their metadata - (``user_api_key_auth``, set in ``add_user_api_key_auth_to_request_metadata``). - The allowlist is enforced at auth time for the request's primary model and - for client-supplied fallbacks in the request body, but a router-configured - fallback swaps the model after auth already ran -- without this check a key - restricted to one model group would be served by any shared deployment the - config lists as a fallback for it. Mirrors the budget_fallbacks re-check in - ``_check_key_model_budget_with_fallback``. Non-proxy (SDK) callers carry no - auth object and are unaffected. + A router-configured fallback swaps the model after auth already ran; + without this check a key restricted to one model group would be served + by any shared deployment the config lists as a fallback for it. + Non-proxy (SDK) callers carry no auth object and are unaffected. """ metadata: Final = kwargs.get("metadata") - if not isinstance(metadata, Mapping): - return True - auth: Final = metadata.get("user_api_key_auth") + litellm_metadata: Final = kwargs.get("litellm_metadata") + auth: Final = ( + metadata.get("user_api_key_auth") if isinstance(metadata, Mapping) else None + ) or ( + litellm_metadata.get("user_api_key_auth") + if isinstance(litellm_metadata, Mapping) + else None + ) if auth is None: return True model: Final = _get_fallback_target_model_group(fallback_entry) @@ -477,31 +477,18 @@ async def _proxy_key_allows_fallback_model( # Inline import: the proxy layer is only reachable when the proxy populated # the metadata above, and a module-level import would be circular. from litellm.proxy._types import ProxyException - from litellm.proxy.auth.auth_checks import ( # pyright: ignore[reportPrivateUsage] # auth_checks exposes no public pair; budget blocks adding one - _can_object_call_model, - can_key_call_model, - ) + from litellm.proxy.auth.auth_checks import can_key_call_resolved_model try: - await can_key_call_model( + await can_key_call_resolved_model( model=model, llm_model_list=None, valid_token=auth, llm_router=litellm_router, ) - team_models: Final = getattr(auth, "team_models", None) - if team_models: - _can_object_call_model( - model=model, - llm_router=litellm_router, - models=team_models, - team_model_aliases=getattr(auth, "team_model_aliases", None), - team_id=getattr(auth, "team_id", None), - object_type="team", - ) except ProxyException: verbose_router_logger.info( - "Skipping fallback to model_group = %s: not allowed for this key/team.", + "Skipping fallback to model_group = %s: not allowed for this key.", mask_sensitive_structure(model), ) return False From 3245454f36871f8260a016ae22756951ea8387f5 Mon Sep 17 00:00:00 2001 From: AUTHENSOR <250658088+AUTHENSOR@users.noreply.github.com> Date: Sun, 20 Sep 2026 03:40:08 -0700 Subject: [PATCH 3/3] test: regression for fallback auth scope check (both metadata buckets) Covers: SDK no-auth passthrough, auth from the metadata bucket, auth from the litellm_metadata bucket (the /v1/messages and /v1/responses path that previously skipped the check), metadata precedence, and the allowed-model pass-through. --- .../test_fallback_model_scope_check.py | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 tests/router_unit_tests/test_fallback_model_scope_check.py diff --git a/tests/router_unit_tests/test_fallback_model_scope_check.py b/tests/router_unit_tests/test_fallback_model_scope_check.py new file mode 100644 index 00000000000..f5732030ba0 --- /dev/null +++ b/tests/router_unit_tests/test_fallback_model_scope_check.py @@ -0,0 +1,112 @@ +"""Regression: server-side fallbacks re-check model authorization. + +A key restricted to model-a should not be served by model-b via a +router-configured fallback, regardless of which metadata bucket carries +the auth object (metadata vs litellm_metadata). +""" + +from unittest.mock import AsyncMock, MagicMock + +import pytest + +from litellm.router_utils.fallback_event_handlers import ( + _proxy_key_allows_fallback_model, +) + + +def _make_kwargs(metadata=None, litellm_metadata=None): + kwargs = {} + if metadata is not None: + kwargs["metadata"] = metadata + if litellm_metadata is not None: + kwargs["litellm_metadata"] = litellm_metadata + return kwargs + + +def _make_auth(team_models=None, key_models=None): + auth = MagicMock() + auth.team_models = team_models or [] + auth.team_model_aliases = None + auth.team_id = None + auth.models = key_models or [] + auth.config = None + return auth + + +@pytest.mark.asyncio +async def test_no_auth_returns_true(): + """SDK callers (no auth object) are unaffected.""" + kwargs = _make_kwargs(metadata={}) + assert await _proxy_key_allows_fallback_model( + litellm_router=MagicMock(), kwargs=kwargs, fallback_entry="model-b" + ) + + +@pytest.mark.asyncio +async def test_metadata_bucket_auth(monkeypatch): + """Auth resolved from kwargs['metadata'] (the standard proxy path).""" + from litellm.proxy.auth import auth_checks + + check = AsyncMock(side_effect=auth_checks.ProxyException(message="denied")) + monkeypatch.setattr(auth_checks, "can_key_call_resolved_model", check) + + kwargs = _make_kwargs(metadata={"user_api_key_auth": _make_auth()}) + result = await _proxy_key_allows_fallback_model( + litellm_router=MagicMock(), kwargs=kwargs, fallback_entry="model-b" + ) + assert result is False + check.assert_called_once() + + +@pytest.mark.asyncio +async def test_litellm_metadata_bucket_auth(monkeypatch): + """Auth resolved from kwargs['litellm_metadata'] (the /v1/messages and + /v1/responses path). Without this, those routes skip the check entirely.""" + from litellm.proxy.auth import auth_checks + + check = AsyncMock(side_effect=auth_checks.ProxyException(message="denied")) + monkeypatch.setattr(auth_checks, "can_key_call_resolved_model", check) + + kwargs = _make_kwargs(litellm_metadata={"user_api_key_auth": _make_auth()}) + result = await _proxy_key_allows_fallback_model( + litellm_router=MagicMock(), kwargs=kwargs, fallback_entry="model-b" + ) + assert result is False + check.assert_called_once() + + +@pytest.mark.asyncio +async def test_metadata_takes_precedence_over_litellm_metadata(monkeypatch): + """When both buckets carry auth, the metadata bucket wins (standard path).""" + from litellm.proxy.auth import auth_checks + + check = AsyncMock() # no exception = allowed + monkeypatch.setattr(auth_checks, "can_key_call_resolved_model", check) + + kwargs = _make_kwargs( + metadata={"user_api_key_auth": _make_auth()}, + litellm_metadata={"user_api_key_auth": _make_auth()}, + ) + result = await _proxy_key_allows_fallback_model( + litellm_router=MagicMock(), kwargs=kwargs, fallback_entry="model-b" + ) + assert result is True + check.assert_called_once() + + +@pytest.mark.asyncio +async def test_allowed_model_returns_true(monkeypatch): + """When the resolved-model check passes, the fallback proceeds.""" + from litellm.proxy.auth import auth_checks + + check = AsyncMock() # no exception = allowed + monkeypatch.setattr(auth_checks, "can_key_call_resolved_model", check) + + kwargs = _make_kwargs(metadata={"user_api_key_auth": _make_auth()}) + result = await _proxy_key_allows_fallback_model( + litellm_router=MagicMock(), kwargs=kwargs, fallback_entry="model-b" + ) + assert result is True + check.assert_called_once_with( + model="model-b", llm_model_list=None, valid_token=kwargs["metadata"]["user_api_key_auth"], llm_router=pytest.ANY + )