From cad362a398c791561e1f2f5acfa62ad2d77caba9 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sun, 8 Nov 2026 22:36:29 +0000 Subject: [PATCH] refactor(auth): port model and route policy to native decisions --- litellm-rust/Cargo.lock | 1 + litellm-rust/crates/python-bridge/src/lib.rs | 33 +- .../crates/python-bridge/src/request_auth.rs | 40 + .../crates/request-auth-core/Cargo.toml | 1 + .../crates/request-auth-core/src/error.rs | 2 + .../request-auth-core/src/fallback_access.rs | 105 ++ .../crates/request-auth-core/src/lib.rs | 6 + .../request-auth-core/src/model_access.rs | 600 +++++++++ .../request-auth-core/src/model_groups.rs | 73 ++ .../request-auth-core/src/org_routes.rs | 119 ++ .../crates/request-auth-core/src/patterns.rs | 134 ++ .../request-auth-core/src/route_access.rs | 567 +++++++++ litellm/_auth/fallback_access.py | 39 + litellm/_auth/model_access.py | 211 ++++ litellm/_auth/model_groups.py | 46 + litellm/_auth/org_routes.py | 51 + litellm/_auth/routes.py | 138 ++ litellm/proxy/auth/fallback_access_adapter.py | 111 ++ litellm/proxy/auth/model_access_adapter.py | 329 +++++ litellm/proxy/auth/model_group_adapter.py | 91 ++ litellm/proxy/auth/org_route_adapter.py | 84 ++ litellm/proxy/auth/route_checks.py | 678 +--------- litellm/proxy/auth/route_policy_adapter.py | 239 ++++ litellm/rust_bridge/_native.pyi | 6 + tests/unit/_auth/support/model_reference.py | 85 ++ tests/unit/_auth/support/route_reference.py | 1120 +++++++++++++++++ tests/unit/_auth/test_fallback_access.py | 62 + tests/unit/_auth/test_model_access.py | 229 ++++ tests/unit/_auth/test_model_groups.py | 49 + tests/unit/_auth/test_routes.py | 192 +++ 30 files changed, 4780 insertions(+), 661 deletions(-) create mode 100644 litellm-rust/crates/request-auth-core/src/fallback_access.rs create mode 100644 litellm-rust/crates/request-auth-core/src/model_access.rs create mode 100644 litellm-rust/crates/request-auth-core/src/model_groups.rs create mode 100644 litellm-rust/crates/request-auth-core/src/org_routes.rs create mode 100644 litellm-rust/crates/request-auth-core/src/patterns.rs create mode 100644 litellm-rust/crates/request-auth-core/src/route_access.rs create mode 100644 litellm/_auth/fallback_access.py create mode 100644 litellm/_auth/model_access.py create mode 100644 litellm/_auth/model_groups.py create mode 100644 litellm/_auth/org_routes.py create mode 100644 litellm/_auth/routes.py create mode 100644 litellm/proxy/auth/fallback_access_adapter.py create mode 100644 litellm/proxy/auth/model_access_adapter.py create mode 100644 litellm/proxy/auth/model_group_adapter.py create mode 100644 litellm/proxy/auth/org_route_adapter.py create mode 100644 litellm/proxy/auth/route_policy_adapter.py create mode 100644 tests/unit/_auth/support/model_reference.py create mode 100644 tests/unit/_auth/support/route_reference.py create mode 100644 tests/unit/_auth/test_fallback_access.py create mode 100644 tests/unit/_auth/test_model_access.py create mode 100644 tests/unit/_auth/test_model_groups.py create mode 100644 tests/unit/_auth/test_routes.py diff --git a/litellm-rust/Cargo.lock b/litellm-rust/Cargo.lock index 53cff103583..d3b4304bc32 100644 --- a/litellm-rust/Cargo.lock +++ b/litellm-rust/Cargo.lock @@ -4409,6 +4409,7 @@ dependencies = [ name = "litellm-request-auth-core" version = "0.1.0" dependencies = [ + "fancy-regex 0.19.2", "litellm-secret-value", "rstest", "serde", diff --git a/litellm-rust/crates/python-bridge/src/lib.rs b/litellm-rust/crates/python-bridge/src/lib.rs index 1d258df8cc8..8592abc06ae 100644 --- a/litellm-rust/crates/python-bridge/src/lib.rs +++ b/litellm-rust/crates/python-bridge/src/lib.rs @@ -39,13 +39,32 @@ mod _native { use crate::model_registry::bundled_model_cost_map; #[pymodule_export] use crate::request_auth::{ - NativeAuthContinuation, request_auth_access, request_auth_admission, - request_auth_budget_alert, request_auth_budget_price, request_auth_budget_route, - request_auth_budget_window_start, request_auth_budgets, request_auth_common_budget, - request_auth_litellm_header_token, request_auth_managed, request_auth_member_limit, - request_auth_model_budget_check, request_auth_model_budget_query, - request_auth_model_budget_resolve, request_auth_scheme_credential, - request_auth_select_api_key, request_auth_select_websocket_api_key, request_auth_start, + NativeAuthContinuation, + request_auth_access, + request_auth_admission, + request_auth_budget_alert, + request_auth_budget_price, + request_auth_budget_route, + request_auth_budget_window_start, + request_auth_budgets, + request_auth_common_budget, + request_auth_fallback_access, + request_auth_litellm_header_token, + request_auth_managed, + request_auth_member_limit, + request_auth_model_access, + request_auth_model_budget_check, + request_auth_model_budget_query, + request_auth_model_budget_resolve, + request_auth_model_groups, + request_auth_org_admin, + request_auth_org_route, + request_auth_route_access, + request_auth_scheme_credential, + request_auth_select_api_key, + request_auth_select_websocket_api_key, + request_auth_start, + ||||||| parent of da364c75e2 (refactor(auth): port model and route policy to native decisions) NativeAuthContinuation, }; #[pymodule_export] use crate::router::{RouterCall, RouterCoreHandle}; diff --git a/litellm-rust/crates/python-bridge/src/request_auth.rs b/litellm-rust/crates/python-bridge/src/request_auth.rs index 33c44f5f78e..23f682f1be4 100644 --- a/litellm-rust/crates/python-bridge/src/request_auth.rs +++ b/litellm-rust/crates/python-bridge/src/request_auth.rs @@ -129,6 +129,7 @@ fn map_error(error: core::Error) -> PyErr { match error { core::Error::IncompatibleDateTimes => PyTypeError::new_err(message), core::Error::InvalidAnswer => PyRuntimeError::new_err(message), + core::Error::Pattern(_) => PyRuntimeError::new_err(message), } } @@ -237,3 +238,42 @@ pub(crate) fn request_auth_scheme_credential(value: &str) -> Option { pub(crate) fn request_auth_litellm_header_token(value: &str) -> String { credential::litellm_header_token(value) } + +#[pyfunction] +pub(crate) fn request_auth_route_access(py: Python<'_>, request: &Bound<'_, PyAny>) -> PyResult> { + let request: core::route_access::Request = from_py(request)?; + let decision = py.detach(move || core::route_access::decide(request)).map_err(map_error)?; + to_py(py, &decision) +} + +#[pyfunction] +pub(crate) fn request_auth_org_route(py: Python<'_>, facts: &Bound<'_, PyAny>) -> PyResult> { + let facts: core::org_routes::Facts = from_py(facts)?; + to_py(py, &py.detach(move || core::org_routes::decide(facts))) +} + +#[pyfunction] +pub(crate) fn request_auth_org_admin(py: Python<'_>, memberships: &Bound<'_, PyAny>, organizations: Vec) -> PyResult { + let memberships: Vec = from_py(memberships)?; + Ok(py.detach(move || core::org_routes::user_is_admin(&memberships, &organizations))) +} + +#[pyfunction] +pub(crate) fn request_auth_model_access(py: Python<'_>, request: &Bound<'_, PyAny>) -> PyResult> { + let request: core::model_access::Request = from_py(request)?; + let decision = py.detach(move || core::model_access::decide(request)).map_err(map_error)?; + to_py(py, &decision) +} + +#[pyfunction] +pub(crate) fn request_auth_model_groups(py: Python<'_>, facts: &Bound<'_, PyAny>) -> PyResult> { + let facts: core::model_groups::Facts = from_py(facts)?; + to_py(py, &py.detach(move || core::model_groups::decide(facts))) +} + +#[pyfunction] +pub(crate) fn request_auth_fallback_access(py: Python<'_>, facts: &Bound<'_, PyAny>) -> PyResult> { + let facts: core::fallback_access::Facts = from_py(facts)?; + let decision = py.detach(move || core::fallback_access::decide(facts)).map_err(map_error)?; + to_py(py, &decision) +} diff --git a/litellm-rust/crates/request-auth-core/Cargo.toml b/litellm-rust/crates/request-auth-core/Cargo.toml index 6b82bde399e..0b51939bb9c 100644 --- a/litellm-rust/crates/request-auth-core/Cargo.toml +++ b/litellm-rust/crates/request-auth-core/Cargo.toml @@ -5,6 +5,7 @@ edition.workspace = true license.workspace = true [dependencies] +fancy-regex.workspace = true litellm-secret-value.workspace = true serde.workspace = true sha2.workspace = true diff --git a/litellm-rust/crates/request-auth-core/src/error.rs b/litellm-rust/crates/request-auth-core/src/error.rs index 6656d9f409c..0f75826b4f7 100644 --- a/litellm-rust/crates/request-auth-core/src/error.rs +++ b/litellm-rust/crates/request-auth-core/src/error.rs @@ -1,5 +1,7 @@ #[derive(Debug, thiserror::Error)] pub enum Error { + #[error("invalid auth pattern")] + Pattern(#[source] fancy_regex::Error), #[error("invalid auth effect answer")] InvalidAnswer, #[error("can't compare offset-naive and offset-aware datetimes")] diff --git a/litellm-rust/crates/request-auth-core/src/fallback_access.rs b/litellm-rust/crates/request-auth-core/src/fallback_access.rs new file mode 100644 index 00000000000..3bcd570a428 --- /dev/null +++ b/litellm-rust/crates/request-auth-core/src/fallback_access.rs @@ -0,0 +1,105 @@ +use serde::{Deserialize, Serialize}; + +use crate::{ + Error, + model_access::{self, Decision as ModelDecision, Facts as ModelFacts, Request, Response}, +}; + +#[derive(Deserialize)] +pub struct GroupedScope { + pub facts: ModelFacts, + pub group_ids: Vec, + pub group_models: Option>, +} + +#[derive(Deserialize)] +pub struct Facts { + pub refuse_agent_keys: bool, + pub agent_id: Option, + pub key: GroupedScope, + pub team: Option, + pub embedded_team: Option, + pub assigned_models: Option>, + pub member: Option, + pub project: Option, +} + +#[derive(Serialize)] +#[serde(tag = "kind")] +pub enum Decision { + Allow, + Deny { denial: Option }, + ReadKeyGroups, + ReadTeamGroups, + ReadAssignedGroups, +} + +fn grouped(scope: GroupedScope, merge: bool) -> Result { + let Response::Decision(decision) = model_access::decide(Request::Grouped { + facts: scope.facts, + group_ids: scope.group_ids, + group_models: scope.group_models, + merge, + })? + else { + return Err(Error::InvalidAnswer); + }; + Ok(decision) +} + +pub fn decide(facts: Facts) -> Result { + if facts.refuse_agent_keys && facts.agent_id.is_some() { + return Ok(Decision::Deny { denial: None }); + } + let key = grouped(facts.key, false)?; + if matches!(key, ModelDecision::ReadGroups) { + return Ok(Decision::ReadKeyGroups); + } + if !key.allowed() { + return Ok(Decision::Deny { denial: Some(key) }); + } + if let Some(team) = facts.team { + let model_facts = team.facts.clone(); + let decision = grouped(team, true)?; + if matches!(decision, ModelDecision::ReadGroups) { + return Ok(Decision::ReadTeamGroups); + } + if !decision.allowed() { + if !matches!(decision, ModelDecision::Deny { .. }) { + return Ok(Decision::Deny { + denial: Some(decision), + }); + } + let Some(grants) = facts.assigned_models else { + return Ok(Decision::ReadAssignedGroups); + }; + if grants.is_empty() + || !model_access::check(&ModelFacts { + grants, + ..model_facts + })? + .allowed() + { + return Ok(Decision::Deny { + denial: Some(decision), + }); + } + } + } else if let Some(team) = facts.embedded_team { + let decision = model_access::check(&team)?; + if !decision.allowed() { + return Ok(Decision::Deny { + denial: Some(decision), + }); + } + } + for scope in [facts.member, facts.project].into_iter().flatten() { + let decision = model_access::check(&scope)?; + if !decision.allowed() { + return Ok(Decision::Deny { + denial: Some(decision), + }); + } + } + Ok(Decision::Allow) +} diff --git a/litellm-rust/crates/request-auth-core/src/lib.rs b/litellm-rust/crates/request-auth-core/src/lib.rs index 2e68905a891..6faceba1f17 100644 --- a/litellm-rust/crates/request-auth-core/src/lib.rs +++ b/litellm-rust/crates/request-auth-core/src/lib.rs @@ -10,6 +10,12 @@ mod key; pub mod managed; pub mod model_budget_data; mod model_budgets; +pub mod patterns; +pub mod route_access; +pub mod org_routes; +pub mod model_access; +pub mod model_groups; +pub mod fallback_access; pub mod protocol; pub use error::Error; diff --git a/litellm-rust/crates/request-auth-core/src/model_access.rs b/litellm-rust/crates/request-auth-core/src/model_access.rs new file mode 100644 index 00000000000..0aba7fd5efa --- /dev/null +++ b/litellm-rust/crates/request-auth-core/src/model_access.rs @@ -0,0 +1,600 @@ +use std::collections::{BTreeMap, BTreeSet}; + +use serde::{Deserialize, Serialize}; + +use crate::{Error, patterns}; + +#[derive(Clone, Default, Deserialize)] +pub struct Provider { + pub stripped_model: String, + pub provider: String, +} + +#[derive(Clone, Default, Deserialize)] +pub struct ModelRecord { + pub access_groups: Vec, + pub provider: Option, + pub deployment_team: Option, + pub deployment_public_name: Option, +} + +#[derive(Clone, Default, Deserialize)] +pub struct Registry { + pub present: bool, + pub names: Vec, + pub aliases: BTreeMap, + pub records: BTreeMap, + pub compaction_parents: BTreeMap, +} + +#[derive(Clone, Default, Deserialize)] +pub struct Aliases { + pub team: BTreeMap, + pub key: BTreeMap, + #[serde(rename = "global_")] + pub global: BTreeMap, +} + +#[derive(Clone, Deserialize)] +pub struct Facts { + pub requested: Vec, + pub grants: Vec, + pub team_id: Option, + pub aliases: Aliases, + pub registry: Registry, + pub object_type: ObjectType, + pub fallback_depth: usize, + pub max_depth: usize, + pub is_list: bool, +} + +#[derive(Clone, Copy, Deserialize, Serialize, Debug, PartialEq, Eq, strum::VariantArray)] +#[serde(rename_all = "snake_case")] +pub enum ObjectType { + User, + Customer, + Team, + Key, + Org, + Project, + Agent, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize)] +#[serde(tag = "kind")] +pub enum Decision { + Allow, + Deny { + model: String, + grants: Vec, + object_type: ObjectType, + }, + Depth { + model: Option, + }, + NoDefaultModels, + NoAgentModels, + EmptyAgentCeiling, + PersonalTeam { + model: String, + }, + ReadGroups, +} + +impl Decision { + pub fn allowed(&self) -> bool { + matches!(self, Self::Allow) + } +} + +fn unique(values: impl Iterator) -> Vec { + let mut seen = BTreeSet::new(); + values.filter(|value| seen.insert(value.clone())).collect() +} + +pub fn resolve_key_grants( + grants: &[String], + team_id: Option<&str>, + team_grants: &[String], +) -> Vec { + if grants.iter().any(|grant| grant == "all-team-models") { + return if team_id.is_none() { + Vec::new() + } else { + team_grants.to_vec() + }; + } + grants.to_vec() +} + +fn expanded_grants(facts: &Facts) -> Vec { + if !facts.grants.iter().any(|grant| grant == "all-team-models") + || facts.team_id.is_none() + || !facts.registry.present + { + return facts.grants.clone(); + } + let others = facts + .grants + .iter() + .filter(|grant| grant.as_str() != "all-team-models") + .cloned(); + if facts.registry.names.is_empty() { + let values: Vec<_> = others.collect(); + return if values.is_empty() { + facts.grants.clone() + } else { + values + }; + } + unique(others.chain(facts.registry.names.iter().cloned())) +} + +fn helper(model: &str, facts: &Facts, aliases: bool) -> Result { + let grants = expanded_grants(facts); + let record = facts.registry.records.get(model); + let groups = record.map_or(&[][..], |record| record.access_groups.as_slice()); + if grants.iter().any(|grant| groups.contains(grant)) { + return Ok(true); + } + let filtered: Vec<_> = grants + .iter() + .filter(|grant| !groups.contains(grant)) + .collect(); + if aliases && facts.aliases.team.contains_key(model) { + return Ok(true); + } + for grant in &filtered { + if patterns::model_pattern(model, grant)? { + return Ok(true); + } + } + if let Some(provider) = record.and_then(|record| record.provider.as_ref()) + && (provider.stripped_model != model || !model.contains('/')) + { + for grant in &filtered { + if patterns::model_pattern( + &format!("{}/{}", provider.provider, provider.stripped_model), + grant, + )? { + return Ok(true); + } + } + } + Ok((filtered.is_empty() && grants.is_empty()) + || filtered.iter().any(|grant| { + matches!(grant.as_str(), "*" | "all-proxy-models") || grant.as_str() == model + })) +} + +pub fn candidate_names( + model: &str, + aliases: &Aliases, + registry: &Registry, + team_id: Option<&str>, +) -> (Vec, Vec) { + let after_team = aliases.team.get(model).map_or(model, String::as_str); + let after_key = aliases + .key + .get(after_team) + .map_or(after_team, String::as_str); + let after_global = aliases + .global + .get(after_key) + .map_or(after_key, String::as_str); + let dispatched = aliases + .key + .get(after_global) + .map_or(after_global, String::as_str); + if after_key != after_team || dispatched != after_global { + return (vec![dispatched.to_owned()], vec![]); + } + let candidates = std::iter::once(model.to_owned()) + .chain(registry.compaction_parents.get(model).cloned()) + .chain( + aliases + .global + .get(model) + .or_else(|| registry.aliases.get(model)) + .filter(|target| !target.is_empty()) + .cloned(), + ) + .collect(); + let Some(team) = team_id else { + return (candidates, vec![]); + }; + if !registry.present || !model.starts_with(&format!("model_name_{team}_")) { + return (candidates, vec![]); + } + let record = registry.records.get(model); + let public = record + .filter(|record| record.deployment_team.as_deref() == Some(team)) + .and_then(|record| record.deployment_public_name.clone()) + .filter(|name| !name.is_empty()); + let legacy = aliases + .team + .iter() + .filter(|(_, target)| target.as_str() == model) + .map(|(alias, _)| alias.clone()); + (candidates, public.into_iter().chain(legacy).collect()) +} + +pub fn live_team_target(model: &str, facts: &Facts) -> String { + let Some(target) = facts.aliases.team.get(model) else { + return model.to_owned(); + }; + let team = facts.team_id.as_deref().unwrap_or("None"); + if facts.registry.present + && target.starts_with(&format!("model_name_{team}_")) + && !facts.registry.names.contains(target) + { + return model.to_owned(); + } + target.clone() +} + +pub fn check(facts: &Facts) -> Result { + if facts.fallback_depth >= facts.max_depth { + return Ok(Decision::Depth { model: None }); + } + for model in &facts.requested { + if facts.is_list && facts.fallback_depth + 1 >= facts.max_depth { + return Ok(Decision::Depth { + model: Some(model.clone()), + }); + } + let (candidates, owning_names) = candidate_names( + model, + &facts.aliases, + &facts.registry, + facts.team_id.as_deref(), + ); + let mut allowed = false; + for candidate in candidates { + if helper(&candidate, facts, true)? { + allowed = true; + break; + } + } + if !allowed { + for candidate in owning_names { + if helper(&candidate, facts, false)? { + allowed = true; + break; + } + } + } + if !allowed { + return Ok(Decision::Deny { + model: model.clone(), + grants: facts.grants.clone(), + object_type: facts.object_type, + }); + } + } + Ok(Decision::Allow) +} + +#[derive(Deserialize)] +pub enum Request { + Object(Facts), + Grouped { + facts: Facts, + group_ids: Vec, + group_models: Option>, + merge: bool, + }, + Helper { + model: String, + facts: Facts, + }, + User { + facts: Facts, + present: bool, + }, + Customer(Facts), + Agent { + facts: Facts, + managed_grants: Option>, + ceilings: Vec>, + }, + Personal { + requested: Vec, + teams: Vec, + }, + KeyGrants { + grants: Vec, + team_id: Option, + team_grants: Vec, + }, + Candidates(Facts), + PersonalApplies { + enabled: bool, + token_present: bool, + team_id: Option, + user_id: Option, + master: bool, + role: Option, + api_key_present: bool, + inheritance: bool, + }, + AssignedGroups { + groups: Vec, + team_id: Option, + key_id: Option, + }, +} + +#[derive(Deserialize)] +pub struct AssignedGroup { + pub assigned_team_ids: Vec, + pub assigned_key_ids: Vec, + pub models: Vec, +} + +#[derive(Deserialize)] +pub struct PersonalTeam { + pub blocked: bool, + pub available: bool, + pub team: Facts, + pub member: Option, +} + +#[derive(Serialize)] +#[serde(untagged)] +pub enum Response { + Decision(Decision), + Models(Vec), + Predicate(bool), +} + +pub fn decide(request: Request) -> Result { + let decision = match request { + Request::Object(facts) => check(&facts)?, + Request::Grouped { + facts, + group_ids, + group_models, + merge, + } => { + let primary = check(&facts)?; + if primary.allowed() + || !matches!(primary, Decision::Deny { .. }) + || group_ids.is_empty() + { + primary + } else if let Some(models) = group_models { + if models.is_empty() { + primary + } else { + check(&Facts { + grants: if merge { + unique(facts.grants.iter().cloned().chain(models)) + } else { + models + }, + ..facts + })? + } + } else { + Decision::ReadGroups + } + } + Request::Helper { model, facts } => { + return Ok(Response::Predicate(helper(&model, &facts, true)?)); + } + Request::User { facts, present } => { + if !present { + Decision::Allow + } else if facts + .grants + .iter() + .any(|grant| grant == "no-default-models") + { + Decision::NoDefaultModels + } else { + check(&facts)? + } + } + Request::Customer(facts) => { + for name in &facts.requested { + let target = live_team_target(name, &facts); + if target != *name && facts.grants.contains(name) { + continue; + } + let customer = Facts { + requested: vec![target], + is_list: false, + team_id: None, + aliases: Aliases { + key: facts.aliases.key.clone(), + global: facts.aliases.global.clone(), + ..Default::default() + }, + ..facts.clone() + }; + let result = check(&customer)?; + if !result.allowed() { + return Ok(Response::Decision(result)); + } + } + Decision::Allow + } + Request::Agent { + facts, + managed_grants, + ceilings, + } => { + if facts.requested.is_empty() + || (facts.requested.len() == 1 && !facts.is_list && facts.requested[0].is_empty()) + { + return Ok(Response::Decision(Decision::Allow)); + } + let dispatched = facts + .requested + .iter() + .map(|name| live_team_target(name, &facts)) + .collect(); + let scope = Facts { + requested: dispatched, + aliases: Aliases { + key: facts.aliases.key.clone(), + global: facts.aliases.global.clone(), + ..Default::default() + }, + object_type: ObjectType::Agent, + ..facts + }; + if let Some(grants) = managed_grants { + if grants.is_empty() { + return Ok(Response::Decision(Decision::NoAgentModels)); + } + let result = check(&Facts { + grants, + ..scope.clone() + })?; + if !result.allowed() { + return Ok(Response::Decision(result)); + } + } + for grants in ceilings { + if grants.is_empty() { + return Ok(Response::Decision(Decision::EmptyAgentCeiling)); + } + let result = check(&Facts { + grants, + ..scope.clone() + })?; + if !result.allowed() { + return Ok(Response::Decision(result)); + } + } + Decision::Allow + } + Request::Personal { requested, teams } => { + for name in requested { + let mut allowed = false; + for team in &teams { + if team.blocked || !team.available { + continue; + } + if !check(&Facts { + requested: vec![name.clone()], + is_list: false, + ..team.team.clone() + })? + .allowed() + { + continue; + } + if let Some(member) = &team.member + && !check(&Facts { + requested: vec![name.clone()], + is_list: false, + ..member.clone() + })? + .allowed() + { + continue; + } + allowed = true; + break; + } + if !allowed { + return Ok(Response::Decision(Decision::PersonalTeam { model: name })); + } + } + Decision::Allow + } + Request::KeyGrants { + grants, + team_id, + team_grants, + } => { + return Ok(Response::Models(resolve_key_grants( + &grants, + team_id.as_deref(), + &team_grants, + ))); + } + Request::Candidates(facts) => { + return Ok(Response::Models(unique(facts.requested.iter().flat_map( + |model| { + let (candidates, owned) = candidate_names( + model, + &facts.aliases, + &facts.registry, + facts.team_id.as_deref(), + ); + candidates.into_iter().chain(owned) + }, + )))); + } + Request::PersonalApplies { + enabled, + token_present, + team_id, + user_id, + master, + role, + api_key_present, + inheritance, + } => { + return Ok(Response::Predicate( + enabled + && token_present + && team_id.is_none() + && user_id.is_some() + && !master + && role.as_deref() != Some("proxy_admin") + && (!inheritance || api_key_present), + )); + } + Request::AssignedGroups { + groups, + team_id, + key_id, + } => { + return Ok(Response::Models(unique( + groups + .into_iter() + .filter(|group| { + team_id.as_ref().is_some_and(|id| { + !id.is_empty() && group.assigned_team_ids.contains(id) + }) || key_id + .as_ref() + .is_some_and(|id| !id.is_empty() && group.assigned_key_ids.contains(id)) + }) + .flat_map(|group| group.models), + ))); + } + }; + Ok(Response::Decision(decision)) +} + +#[cfg(test)] +mod tests { + use super::*; + use rstest::rstest; + + #[rstest] + #[case::empty(vec![], true)] + #[case::wildcard(vec!["*"], true)] + #[case::proxy(vec!["all-proxy-models"], true)] + #[case::other(vec!["other"], false)] + #[case::exact(vec!["model"], true)] + fn model_grants(#[case] grants: Vec<&str>, #[case] expected: bool) { + let facts = Facts { + requested: vec!["model".into()], + grants: grants.into_iter().map(str::to_owned).collect(), + team_id: None, + aliases: Aliases::default(), + registry: Registry::default(), + object_type: ObjectType::Key, + fallback_depth: 0, + max_depth: 10, + is_list: false, + }; + assert_eq!(check(&facts).unwrap().allowed(), expected); + } +} diff --git a/litellm-rust/crates/request-auth-core/src/model_groups.rs b/litellm-rust/crates/request-auth-core/src/model_groups.rs new file mode 100644 index 00000000000..7853d4b2c5f --- /dev/null +++ b/litellm-rust/crates/request-auth-core/src/model_groups.rs @@ -0,0 +1,73 @@ +use std::collections::BTreeSet; + +use serde::{Deserialize, Serialize}; + +#[derive(Deserialize)] +pub struct Group { + pub assigned_team_ids: Vec, + pub assigned_key_ids: Vec, + pub resources: Vec, +} + +#[derive(Deserialize)] +#[serde(tag = "kind", content = "group")] +pub enum Lookup { + Found(Group), + Missing, + Failed, +} + +#[derive(Deserialize)] +pub struct Facts { + pub subject_present: bool, + pub database_present: bool, + pub cache_present: bool, + pub group_ids: Vec, + pub team_id: Option, + pub key_id: Option, + pub check_db_only: bool, + pub strict_errors: bool, + pub loaded: Vec, +} + +#[derive(Serialize)] +#[serde(tag = "kind")] +pub enum Decision { + Read { index: usize }, + Raise { index: usize }, + Complete { resources: Vec }, +} + +pub fn decide(facts: Facts) -> Decision { + if !facts.subject_present || !facts.database_present || !facts.cache_present { + return Decision::Complete { resources: vec![] }; + } + let mut resources = BTreeSet::new(); + for index in 0..facts.group_ids.len() { + let Some(loaded) = facts.loaded.get(index) else { + return Decision::Read { index }; + }; + match loaded { + Lookup::Missing | Lookup::Failed if facts.check_db_only || facts.strict_errors => { + return Decision::Raise { index }; + } + Lookup::Missing | Lookup::Failed => {} + Lookup::Found(group) => { + if facts + .team_id + .as_ref() + .is_some_and(|id| !id.is_empty() && group.assigned_team_ids.contains(id)) + || facts + .key_id + .as_ref() + .is_some_and(|id| !id.is_empty() && group.assigned_key_ids.contains(id)) + { + resources.extend(group.resources.iter().cloned()); + } + } + } + } + Decision::Complete { + resources: resources.into_iter().collect(), + } +} diff --git a/litellm-rust/crates/request-auth-core/src/org_routes.rs b/litellm-rust/crates/request-auth-core/src/org_routes.rs new file mode 100644 index 00000000000..9f34c02db33 --- /dev/null +++ b/litellm-rust/crates/request-auth-core/src/org_routes.rs @@ -0,0 +1,119 @@ +use serde::{Deserialize, Serialize}; + +#[derive(Clone, Deserialize)] +pub struct Membership { + pub organization_id: Option, + pub role: Option, +} + +#[derive(Deserialize)] +pub struct Facts { + pub route: String, + pub user_present: bool, + pub user_role: Option, + pub memberships: Option>, + pub organization_id: Option, + pub org_admin_routes: Vec, +} + +#[derive(Debug, PartialEq, Eq, Serialize, strum::VariantArray)] +pub enum Denial { + CreateOrganization, + NoMemberships, + MissingOrganization, + MissingRole, + WrongRole, + TeamMissingOrganization, + TeamWrongRole, +} + +#[derive(Debug, PartialEq, Eq, Serialize)] +pub struct Decision { + pub denial: Option, + pub organization_role: Option, + pub organization_ids: Vec, +} + +pub fn decide(facts: Facts) -> Decision { + let memberships = facts.memberships.as_deref().unwrap_or(&[]); + let ids = memberships + .iter() + .filter_map(|item| item.organization_id.clone()) + .collect(); + let role = memberships + .iter() + .rev() + .find(|item| { + item.organization_id.is_some() && item.organization_id == facts.organization_id + }) + .and_then(|item| item.role.clone()); + let denial = if !facts.user_present || facts.user_role.as_deref() == Some("proxy_admin") { + None + } else if facts.route == "/organization/new" { + Some(Denial::CreateOrganization) + } else if facts.org_admin_routes.contains(&facts.route) { + if facts.memberships.is_none() { + Some(Denial::NoMemberships) + } else if facts.organization_id.is_none() { + Some(Denial::MissingOrganization) + } else if role.is_none() { + Some(Denial::MissingRole) + } else if role.as_deref() != Some("org_admin") { + Some(Denial::WrongRole) + } else { + None + } + } else if facts.route == "/team/new" && !memberships.is_empty() { + if facts.organization_id.is_none() { + Some(Denial::TeamMissingOrganization) + } else if role.as_deref() != Some("org_admin") { + Some(Denial::TeamWrongRole) + } else { + None + } + } else { + None + }; + Decision { + denial, + organization_role: role, + organization_ids: ids, + } +} + +pub fn user_is_admin(memberships: &[Membership], organizations: &[String]) -> bool { + !organizations.is_empty() + && organizations.iter().all(|id| { + memberships.iter().any(|item| { + item.organization_id.as_ref() == Some(id) + && item.role.as_deref() == Some("org_admin") + }) + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use rstest::rstest; + + #[rstest] + #[case::none(None, Some(Denial::NoMemberships))] + #[case::empty(Some(vec![]), Some(Denial::MissingOrganization))] + fn membership_presence( + #[case] memberships: Option>, + #[case] expected: Option, + ) { + assert_eq!( + decide(Facts { + route: "/organization/update".into(), + user_present: true, + user_role: None, + memberships, + organization_id: None, + org_admin_routes: vec!["/organization/update".into()] + }) + .denial, + expected + ); + } +} diff --git a/litellm-rust/crates/request-auth-core/src/patterns.rs b/litellm-rust/crates/request-auth-core/src/patterns.rs new file mode 100644 index 00000000000..dc378e0f01b --- /dev/null +++ b/litellm-rust/crates/request-auth-core/src/patterns.rs @@ -0,0 +1,134 @@ +use fancy_regex::Regex; +use std::{ + collections::BTreeMap, + sync::{Arc, LazyLock, Mutex}, +}; + +use crate::Error; + +static EXPRESSIONS: LazyLock>>> = + LazyLock::new(|| Mutex::new(BTreeMap::new())); + +fn expression(pattern: &str) -> Result, Error> { + if let Some(compiled) = EXPRESSIONS + .lock() + .unwrap_or_else(|error| error.into_inner()) + .get(pattern) + { + return Ok(Arc::clone(compiled)); + } + let compiled = Arc::new(Regex::new(pattern).map_err(Error::Pattern)?); + let mut expressions = EXPRESSIONS + .lock() + .unwrap_or_else(|error| error.into_inner()); + if expressions.len() >= 1024 { + expressions.clear(); + } + expressions.insert(pattern.to_owned(), Arc::clone(&compiled)); + Ok(compiled) +} + +pub fn regex_match(pattern: &str, value: &str) -> Result { + let expression = expression(pattern)?; + Ok(expression + .find(value) + .map_err(Error::Pattern)? + .is_some_and(|found| found.start() == 0)) +} + +pub fn model_pattern(model: &str, pattern: &str) -> Result { + if !pattern.contains('*') { + return Ok(false); + } + regex_match( + &format!("^{}(?=\\n?\\z)", pattern.replace('*', ".*")), + model, + ) +} + +pub fn route_pattern(route: &str, pattern: &str) -> Result { + let mut expression = String::from("^"); + let mut rest = pattern; + while let Some(start) = rest.find('{') { + expression.push_str(&rest[..start]); + let Some(end) = rest[start + 1..].find('}').map(|index| index + start + 1) else { + expression.push_str(&rest[start..]); + rest = ""; + break; + }; + let name = &rest[start + 1..end]; + if name.is_empty() { + expression.push_str("{}"); + } else if name.ends_with(":path") { + expression.push_str(if rest[end + 1..].contains(':') { + "[^:]+" + } else { + "[\\s\\S]+" + }); + } else { + expression.push_str("[^/]+"); + } + rest = &rest[end + 1..]; + } + expression.push_str(rest); + expression.push_str("(?=\\n?\\z)"); + regex_match(&expression, route) +} + +pub fn wildcard(route: &str, pattern: &str) -> bool { + pattern + .strip_suffix('*') + .map_or(route == pattern, |prefix| route.starts_with(prefix)) +} + +pub fn prefix(route: &str, pattern: &str) -> bool { + route == pattern + || route + .strip_prefix(pattern) + .is_some_and(|suffix| suffix.starts_with('/')) +} + +pub fn route_access(route: &str, patterns: &[String]) -> Result { + if patterns + .iter() + .any(|pattern| pattern == route || (pattern.ends_with('*') && wildcard(route, pattern))) + { + return Ok(true); + } + for pattern in patterns { + if route_pattern(route, pattern)? { + return Ok(true); + } + } + Ok(false) +} + +#[cfg(test)] +mod tests { + use rstest::rstest; + + #[rstest] + #[case::segment("/key/k/reset", "/key/{id}/reset", true)] + #[case::segment_slash("/key/a/b/reset", "/key/{id}/reset", false)] + #[case::path_slash("/credentials/a/b/start", "/credentials/{id:path}/start", true)] + #[case::path_newline("/credentials/a\nb/start", "/credentials/{id:path}/start", true)] + #[case::google_suffix( + "/models/a:b:generateContent", + "/models/{id:path}:generateContent", + false + )] + #[case::final_newline("/models/a\n", "/models/{id}", true)] + fn route_templates(#[case] route: &str, #[case] pattern: &str, #[case] expected: bool) { + assert_eq!(super::route_pattern(route, pattern).unwrap(), expected); + } + + #[rstest] + #[case::provider("openai/a", "openai/*", true)] + #[case::exact_not_pattern("a", "a", false)] + #[case::regex_dot("aa-1", "a.-*", true)] + #[case::newline("a\nb", "*", false)] + #[case::final_newline("a\n", "a*", true)] + fn model_patterns(#[case] model: &str, #[case] pattern: &str, #[case] expected: bool) { + assert_eq!(super::model_pattern(model, pattern).unwrap(), expected); + } +} diff --git a/litellm-rust/crates/request-auth-core/src/route_access.rs b/litellm-rust/crates/request-auth-core/src/route_access.rs new file mode 100644 index 00000000000..b1eb51177bf --- /dev/null +++ b/litellm-rust/crates/request-auth-core/src/route_access.rs @@ -0,0 +1,567 @@ +use std::collections::BTreeMap; + +use serde::{Deserialize, Serialize}; + +use crate::{Error, patterns}; + +#[derive(Clone, Default, Deserialize)] +pub struct RouteCatalog { + pub groups: BTreeMap>, + pub viewer_blocked: Vec, + pub viewer_write_blocked: Vec, + pub self_credentials: Vec<(String, String)>, + pub managed_models: Vec, + pub managed_paths: Vec, + pub managed_realtime: Vec, + pub managed_live: Vec, + pub managed_mcp: Vec, + pub unbilled: Vec, +} + +impl RouteCatalog { + fn group(&self, name: &str) -> &[String] { + self.groups.get(name).map_or(&[], Vec::as_slice) + } + + fn access(&self, route: &str, name: &str) -> Result { + patterns::route_access(route, self.group(name)) + } + + fn contains(&self, route: &str, name: &str) -> bool { + self.group(name).iter().any(|entry| entry == route) + } +} + +#[derive(Clone, Default, Deserialize)] +pub struct RouteContext { + pub route: String, + pub method: Option, + pub catalog: RouteCatalog, + pub registered: bool, + pub registered_auth: Option, + pub configured_eu_jev: bool, +} + +#[derive(Clone, Default, Deserialize)] +pub struct PassThroughFacts { + pub key_allowed: Vec, + pub team_allowed: Vec, + pub denied: Vec, + pub forwarded: Vec, + pub jwt_team_routes: Vec, +} + +#[derive(Deserialize)] +pub struct VirtualRouteFacts { + pub context: RouteContext, + pub allowed_routes: Option>, + pub passthrough: PassThroughFacts, + pub password_reset_required: bool, +} + +#[derive(Deserialize)] +pub struct ViewerFacts { + pub context: RouteContext, + pub request_keys: Vec, +} + +#[derive(Deserialize)] +pub struct NonAdminFacts { + pub viewer: ViewerFacts, + pub role: Option, + pub custom_admin_routes: Vec, + pub premium: bool, + pub query_user_id: Option, + pub token_user_id: Option, + pub permissions: Vec, + pub organization_ids: Vec, + pub admin_organization_ids: Vec, + pub team_service_account: bool, + pub allowed_routes: Option>, + pub passthrough: PassThroughFacts, +} + +#[derive(Deserialize)] +pub struct MatchFacts { + pub route: String, + pub patterns: Vec, + pub mode: MatchMode, +} + +#[derive(Deserialize, strum::VariantArray)] +pub enum MatchMode { + Access, + Template, + Prefix, + Wildcard, + Denied, + Jwt, +} + +#[derive(Deserialize, strum::VariantArray)] +pub enum Classification { + Llm, + Unbilled, + Discovery, + SelfCredential, + Azure, + Managed, +} + +#[derive(Deserialize)] +pub enum Request { + Match(MatchFacts), + Classify { + context: RouteContext, + kind: Classification, + }, + Virtual(VirtualRouteFacts), + Viewer(ViewerFacts), + NonAdmin(NonAdminFacts), + PassThrough { + context: RouteContext, + facts: PassThroughFacts, + required: bool, + }, + DeniedPassThrough { + route: String, + facts: PassThroughFacts, + }, +} + +#[derive(Debug, PartialEq, Eq, Serialize)] +pub struct Decision { + pub allowed: bool, + pub denial: Option, + pub detail: Option, +} + +#[derive(Debug, PartialEq, Eq, Serialize, strum::VariantArray)] +pub enum Denial { + VirtualRoute, + PasswordReset, + PassThrough, + DeniedPassThrough, + CustomAdmin, + UserInfo, + AdminOnly, + ViewerInference, + ViewerWrite, + ViewerParameter, +} + +impl Decision { + fn allow() -> Self { + Self { + allowed: true, + denial: None, + detail: None, + } + } + fn predicate(value: bool) -> Self { + Self { + allowed: value, + denial: None, + detail: None, + } + } + fn deny(denial: Denial) -> Self { + Self { + allowed: false, + denial: Some(denial), + detail: None, + } + } + fn detail(denial: Denial, detail: String) -> Self { + Self { + allowed: false, + denial: Some(denial), + detail: Some(detail), + } + } +} + +fn denied_pattern(route: &str, pattern: &str) -> bool { + let normalized = pattern.trim_end_matches('/'); + normalized.is_empty() + || patterns::prefix(route, normalized) + || patterns::wildcard(route, pattern) +} + +fn jwt_grant(route: &str, entries: &[String]) -> bool { + entries.iter().any(|entry| { + !entry.trim_end_matches('*').trim_matches('/').is_empty() + && patterns::wildcard(route, entry) + }) +} + +fn passthrough_grant(route: &str, facts: &PassThroughFacts) -> bool { + let entries = if facts.key_allowed.is_empty() { + &facts.team_allowed + } else { + &facts.key_allowed + }; + entries.iter().any(|entry| patterns::prefix(route, entry)) +} + +fn denied_passthrough(facts: &PassThroughFacts) -> Option<&str> { + facts + .denied + .iter() + .find(|denied| { + facts + .forwarded + .iter() + .any(|route| denied_pattern(route, denied)) + }) + .map(String::as_str) +} + +fn require_passthrough(route: &str, facts: &PassThroughFacts) -> Decision { + if let Some(denied) = denied_passthrough(facts) { + return Decision::detail(Denial::DeniedPassThrough, denied.to_owned()); + } + if passthrough_grant(route, facts) || jwt_grant(route, &facts.jwt_team_routes) { + return Decision::allow(); + } + Decision::deny(Denial::PassThrough) +} + +fn azure(route: &str) -> Result { + Ok(patterns::regex_match( + "^/openai/deployments/[^/]+/[^/]+/chat/completions(?=\\n?\\z)", + route, + )? || patterns::regex_match("^/engines/[^/]+/chat/completions(?=\\n?\\z)", route)?) +} + +fn llm(context: &RouteContext) -> Result { + let route = &context.route; + let catalog = &context.catalog; + for group in ["openai_routes", "anthropic_routes", "google_routes"] { + if catalog.contains(route, group) { + return Ok(true); + } + } + for group in [ + "mcp_inference_routes", + "agent_inference_routes", + "litellm_native_routes", + ] { + if catalog.access(route, group)? { + return Ok(true); + } + } + for group in ["openai_routes", "google_routes", "anthropic_routes"] { + for pattern in catalog.group(group) { + if pattern.contains('{') && patterns::route_pattern(route, pattern)? { + return Ok(true); + } + if group == "openai_routes" + && pattern.ends_with('*') + && patterns::wildcard(route, pattern) + { + return Ok(true); + } + } + } + Ok(azure(route)? + || catalog + .group("mapped_pass_through_routes") + .iter() + .any(|pattern| patterns::prefix(route, pattern)) + || (route.trim_end_matches('/') == "/eu_jev/v1/systemone" && !context.configured_eu_jev)) +} + +fn discovery(context: &RouteContext) -> bool { + context.method.as_deref() == Some("GET") + && (context.route == "/v1/mcp/server" + || context + .route + .strip_prefix("/v1/mcp/server/") + .is_some_and(|tail| !tail.is_empty() && !tail.contains('/'))) +} + +fn self_credential(context: &RouteContext) -> Result { + for (method, pattern) in &context.catalog.self_credentials { + if context.method.as_ref() == Some(method) + && patterns::route_access(&context.route, std::slice::from_ref(pattern))? + { + return Ok(true); + } + } + Ok(false) +} + +fn managed(context: &RouteContext) -> Result { + let route = &context.route; + let method = context.method.as_deref(); + let catalog = &context.catalog; + if route == "/agents" || route == "/v1/agents" { + return Ok(matches!(method, None | Some("GET" | "HEAD"))); + } + if catalog.managed_realtime.contains(route) || catalog.managed_live.contains(route) { + return Ok(matches!(method, None | Some("GET"))); + } + if catalog.managed_models.contains(route) + || patterns::route_access(route, &catalog.managed_paths)? + { + return Ok(matches!(method, None | Some("POST"))); + } + Ok(patterns::route_access(route, &catalog.managed_mcp)? + || catalog.access(route, "agent_inference_routes")?) +} + +fn virtual_route(facts: &VirtualRouteFacts) -> Result { + let Some(allowed) = &facts.allowed_routes else { + return Ok(Decision::allow()); + }; + if allowed.is_empty() { + return Ok(Decision::allow()); + } + let context = &facts.context; + let route = &context.route; + if allowed + .iter() + .any(|pattern| patterns::prefix(route, pattern)) + { + return Ok(Decision::allow()); + } + let mut denied_passthrough = false; + for group in allowed { + if !context.catalog.groups.contains_key(group) { + continue; + } + let is_llm = matches!( + group.as_str(), + "llm_api_routes" | "llm_api_routes_without_mcp" + ); + if context.catalog.access(route, group)? { + if (is_llm || group == "openai_routes") && context.registered_auth == Some(true) { + if passthrough_grant(route, &facts.passthrough) { + return Ok(Decision::allow()); + } + denied_passthrough = true; + } else { + return Ok(Decision::allow()); + } + } + if !is_llm { + continue; + } + if route == "/auto_router/session" && context.method.as_deref() == Some("GET") { + return Ok(Decision::allow()); + } + if context.registered { + if context.registered_auth == Some(true) { + if passthrough_grant(route, &facts.passthrough) { + return Ok(Decision::allow()); + } + denied_passthrough = true; + } else { + return Ok(Decision::allow()); + } + } + if group == "llm_api_routes" + && (discovery(context) || context.catalog.access(route, "agent_management_routes")?) + { + return Ok(Decision::allow()); + } + } + if allowed + .iter() + .any(|pattern| patterns::wildcard(route, pattern)) + { + return Ok(Decision::allow()); + } + Ok(Decision::deny(if denied_passthrough { + Denial::PassThrough + } else if facts.password_reset_required { + Denial::PasswordReset + } else { + Denial::VirtualRoute + })) +} + +fn viewer(facts: &ViewerFacts) -> Result { + let context = &facts.context; + let route = &context.route; + let catalog = &context.catalog; + if llm(context)? { + return Ok(Decision::deny(Denial::ViewerInference)); + } + let invalid = facts + .request_keys + .iter() + .find(|key| key.as_str() != "user_email"); + if catalog.access(route, "management_routes")? { + if route == "/user/update" { + if let Some(key) = invalid { + return Ok(Decision::detail(Denial::ViewerParameter, key.clone())); + } + } else if patterns::route_access(route, &catalog.viewer_blocked)? + || (route.starts_with("/key/") + && (route.ends_with("/regenerate") || route.ends_with("/reset_spend"))) + { + return Ok(Decision::deny(Denial::ViewerWrite)); + } + } + if matches!( + context.method.as_deref().unwrap_or("GET"), + "GET" | "HEAD" | "OPTIONS" + ) { + return Ok(Decision::allow()); + } + if route == "/user/update" { + return Ok(invalid.map_or_else(Decision::allow, |key| { + Decision::detail(Denial::ViewerParameter, key.clone()) + })); + } + if route == "/user/password/change" || route == "/session/logout" || self_credential(context)? { + return Ok(Decision::allow()); + } + if patterns::route_access(route, &catalog.viewer_write_blocked)? + || (route.starts_with("/key/") && route.ends_with("/regenerate")) + { + return Ok(Decision::deny(Denial::ViewerWrite)); + } + if catalog.access(route, "admin_viewer_routes")? + || catalog.access(route, "global_spend_tracking_routes")? + { + return Ok(Decision::allow()); + } + Ok(Decision::deny(Denial::ViewerWrite)) +} + +fn non_admin(facts: &NonAdminFacts) -> Result { + let context = &facts.viewer.context; + let route = &context.route; + let catalog = &context.catalog; + let role = facts.role.as_deref(); + if facts.premium && facts.custom_admin_routes.contains(route) { + return Ok(Decision::deny(Denial::CustomAdmin)); + } + if context.registered_auth == Some(true) { + return Ok(require_passthrough(route, &facts.passthrough)); + } + if llm(context)? { + return Ok(Decision::allow()); + } + if catalog.contains(route, "info_routes") { + if route == "/user/info" + && facts + .query_user_id + .as_ref() + .is_some_and(|id| !id.is_empty()) + && facts.query_user_id != facts.token_user_id + && role != Some("proxy_admin_viewer") + { + return Ok(Decision::deny(Denial::UserInfo)); + } + return Ok(Decision::allow()); + } + if catalog.contains(route, "global_spend_tracking_routes") + && facts + .permissions + .iter() + .any(|entry| entry == "get_spend_routes") + { + return Ok(Decision::allow()); + } + if patterns::prefix(route, "/lens") { + return Ok(Decision::allow()); + } + if role == Some("proxy_admin_viewer") { + return viewer(&facts.viewer); + } + let org_admin = !facts.organization_ids.is_empty() + && facts + .organization_ids + .iter() + .all(|id| facts.admin_organization_ids.contains(id)); + if (role == Some("internal_user") + && (catalog.access(route, "internal_user_routes")? || self_credential(context)?)) + || (org_admin && catalog.access(route, "org_admin_allowed_routes")?) + || (role == Some("internal_user_viewer") + && catalog.access(route, "internal_user_view_only_routes")?) + || catalog.access(route, "self_managed_routes")? + || route.starts_with("/v1/mcp/") + || route.starts_with("/mcp-rest/") + || passthrough_grant(route, &facts.passthrough) + || (facts.team_service_account + && catalog.access(route, "team_service_account_key_routes")?) + { + return Ok(Decision::allow()); + } + if facts.allowed_routes.as_ref().is_some_and(|entries| { + entries + .iter() + .any(|entry| patterns::prefix(route, entry) || patterns::wildcard(route, entry)) + }) { + return Ok(Decision::allow()); + } + Ok(Decision::deny(Denial::AdminOnly)) +} + +pub fn decide(request: Request) -> Result { + match request { + Request::Virtual(facts) => virtual_route(&facts), + Request::Viewer(facts) => viewer(&facts), + Request::NonAdmin(facts) => non_admin(&facts), + Request::PassThrough { + context, + facts, + required, + } => Ok(if required { + require_passthrough(&context.route, &facts) + } else { + Decision::predicate(passthrough_grant(&context.route, &facts)) + }), + Request::DeniedPassThrough { route: _, facts } => Ok(denied_passthrough(&facts) + .map_or_else(Decision::allow, |entry| { + Decision::detail(Denial::DeniedPassThrough, entry.to_owned()) + })), + Request::Match(facts) => { + let matched = match facts.mode { + MatchMode::Access => patterns::route_access(&facts.route, &facts.patterns)?, + MatchMode::Jwt => jwt_grant(&facts.route, &facts.patterns), + MatchMode::Template => { + let mut found = false; + for pattern in &facts.patterns { + if patterns::route_pattern(&facts.route, pattern)? { + found = true; + break; + } + } + found + } + MatchMode::Prefix => facts + .patterns + .iter() + .any(|pattern| patterns::prefix(&facts.route, pattern)), + MatchMode::Wildcard => facts + .patterns + .iter() + .any(|pattern| patterns::wildcard(&facts.route, pattern)), + MatchMode::Denied => facts + .patterns + .iter() + .any(|pattern| denied_pattern(&facts.route, pattern)), + }; + Ok(Decision::predicate(matched)) + } + Request::Classify { context, kind } => Ok(Decision::predicate(match kind { + Classification::Llm => llm(&context)?, + Classification::Azure => azure(&context.route)?, + Classification::Discovery => discovery(&context), + Classification::SelfCredential => self_credential(&context)?, + Classification::Managed => managed(&context)?, + Classification::Unbilled => { + let tail = context.route.rsplit('/').next().unwrap_or(""); + let (resource, action) = tail.split_once(':').unwrap_or((tail, "")); + context.catalog.unbilled.contains(&context.route) + || matches!(resource, "count_tokens" | "count-tokens") + || action == "countTokens" + } + })), + } +} diff --git a/litellm/_auth/fallback_access.py b/litellm/_auth/fallback_access.py new file mode 100644 index 00000000000..70014e26c58 --- /dev/null +++ b/litellm/_auth/fallback_access.py @@ -0,0 +1,39 @@ +from dataclasses import asdict, dataclass +from typing import Final, Literal + +from pydantic import TypeAdapter + +from litellm._auth.model_access import ModelAccessDecision, ModelAccessFacts +from litellm.rust_bridge import _native + + +@dataclass(frozen=True, slots=True) +class GroupedModelScope: + facts: ModelAccessFacts + group_ids: tuple[str, ...] = () + group_models: tuple[str, ...] | None = None + + +@dataclass(frozen=True, slots=True) +class FallbackAuthorizationFacts: + key: GroupedModelScope + refuse_agent_keys: bool = False + agent_id: str | None = None + team: GroupedModelScope | None = None + embedded_team: ModelAccessFacts | None = None + assigned_models: tuple[str, ...] | None = None + member: ModelAccessFacts | None = None + project: ModelAccessFacts | None = None + + +@dataclass(frozen=True, slots=True) +class FallbackAuthorizationDecision: + kind: Literal["Allow", "Deny", "ReadKeyGroups", "ReadTeamGroups", "ReadAssignedGroups"] + denial: ModelAccessDecision | None = None + + +_DECISION: Final = TypeAdapter(FallbackAuthorizationDecision) + + +def fallback_authorization(facts: FallbackAuthorizationFacts) -> FallbackAuthorizationDecision: + return _DECISION.validate_python(_native.request_auth_fallback_access(asdict(facts))) diff --git a/litellm/_auth/model_access.py b/litellm/_auth/model_access.py new file mode 100644 index 00000000000..375adfd2a7c --- /dev/null +++ b/litellm/_auth/model_access.py @@ -0,0 +1,211 @@ +from collections.abc import Mapping +from dataclasses import asdict, dataclass, field +from typing import Final, Literal, TypeAlias + +from pydantic import TypeAdapter + +from litellm.rust_bridge import _native + +ModelObject: TypeAlias = Literal["user", "customer", "team", "key", "org", "project", "agent"] + + +@dataclass(frozen=True, slots=True) +class ModelProvider: + stripped_model: str + provider: str + + +@dataclass(frozen=True, slots=True) +class ModelRecord: + access_groups: tuple[str, ...] = () + provider: ModelProvider | None = None + deployment_team: str | None = None + deployment_public_name: str | None = None + + +@dataclass(frozen=True, slots=True) +class ModelRegistry: + present: bool = False + names: tuple[str, ...] = () + aliases: Mapping[str, str] = field(default_factory=dict[str, str]) + records: Mapping[str, ModelRecord] = field(default_factory=dict[str, ModelRecord]) + compaction_parents: Mapping[str, str] = field(default_factory=dict[str, str]) + + +@dataclass(frozen=True, slots=True) +class ModelAliases: + team: Mapping[str, str] = field(default_factory=dict[str, str]) + key: Mapping[str, str] = field(default_factory=dict[str, str]) + global_: Mapping[str, str] = field(default_factory=dict[str, str]) + + +@dataclass(frozen=True, slots=True) +class ModelAccessFacts: + requested: tuple[str, ...] + grants: tuple[str, ...] = () + team_id: str | None = None + aliases: ModelAliases = field(default_factory=ModelAliases) + registry: ModelRegistry = field(default_factory=ModelRegistry) + object_type: ModelObject = "user" + fallback_depth: int = 0 + max_depth: int = 5 + is_list: bool = False + + +@dataclass(frozen=True, slots=True) +class ModelAccessDecision: + kind: Literal[ + "Allow", "Deny", "Depth", "NoDefaultModels", "NoAgentModels", "EmptyAgentCeiling", "PersonalTeam", "ReadGroups" + ] + model: str | None = None + grants: tuple[str, ...] = () + object_type: ModelObject = "user" + + +@dataclass(frozen=True, slots=True) +class AssignedModelGroup: + assigned_team_ids: tuple[str, ...] + assigned_key_ids: tuple[str, ...] + models: tuple[str, ...] + + +@dataclass(frozen=True, slots=True) +class PersonalModelTeam: + blocked: bool + available: bool + team: ModelAccessFacts + member: ModelAccessFacts | None = None + + +_DECISION: Final = TypeAdapter(ModelAccessDecision) +_MODELS: Final = TypeAdapter(tuple[str, ...]) +_BOOL: Final = TypeAdapter(bool) + + +def model_access(facts: ModelAccessFacts, *, kind: Literal["Object", "Customer"] = "Object") -> ModelAccessDecision: + return _DECISION.validate_python(_native.request_auth_model_access({kind: asdict(facts)})) + + +def grouped_model_access( + facts: ModelAccessFacts, + group_ids: tuple[str, ...], + group_models: tuple[str, ...] | None = None, + *, + merge: bool = False, +) -> ModelAccessDecision: + return _DECISION.validate_python( + _native.request_auth_model_access( + { + "Grouped": { + "facts": asdict(facts), + "group_ids": group_ids, + "group_models": group_models, + "merge": merge, + } + } + ) + ) + + +def user_model_access(facts: ModelAccessFacts, *, present: bool) -> ModelAccessDecision: + return _DECISION.validate_python( + _native.request_auth_model_access({"User": {"facts": asdict(facts), "present": present}}) + ) + + +def agent_model_access( + facts: ModelAccessFacts, managed_grants: tuple[str, ...] | None, ceilings: tuple[tuple[str, ...], ...] +) -> ModelAccessDecision: + return _DECISION.validate_python( + _native.request_auth_model_access( + { + "Agent": { + "facts": asdict(facts), + "managed_grants": managed_grants, + "ceilings": ceilings, + } + } + ) + ) + + +def personal_model_access(requested: tuple[str, ...], teams: tuple[PersonalModelTeam, ...]) -> ModelAccessDecision: + return _DECISION.validate_python( + _native.request_auth_model_access( + { + "Personal": { + "requested": requested, + "teams": tuple(asdict(team) for team in teams), + } + } + ) + ) + + +def model_candidates(facts: ModelAccessFacts) -> tuple[str, ...]: + return _MODELS.validate_python(_native.request_auth_model_access({"Candidates": asdict(facts)})) + + +def model_access_helper(model: str, facts: ModelAccessFacts) -> bool: + return _BOOL.validate_python( + _native.request_auth_model_access({"Helper": {"model": model, "facts": asdict(facts)}}) + ) + + +def key_model_grants(grants: tuple[str, ...], team_id: str | None, team_grants: tuple[str, ...]) -> tuple[str, ...]: + return _MODELS.validate_python( + _native.request_auth_model_access( + { + "KeyGrants": { + "grants": grants, + "team_id": team_id, + "team_grants": team_grants, + } + } + ) + ) + + +def assigned_model_grants( + groups: tuple[AssignedModelGroup, ...], team_id: str | None, key_id: str | None +) -> tuple[str, ...]: + return _MODELS.validate_python( + _native.request_auth_model_access( + { + "AssignedGroups": { + "groups": tuple(asdict(group) for group in groups), + "team_id": team_id, + "key_id": key_id, + } + } + ) + ) + + +def personal_model_access_applies( + *, + enabled: bool, + token_present: bool, + team_id: str | None, + user_id: str | None, + master: bool, + role: str | None, + api_key_present: bool, + inheritance: bool = False, +) -> bool: + return _BOOL.validate_python( + _native.request_auth_model_access( + { + "PersonalApplies": { + "enabled": enabled, + "token_present": token_present, + "team_id": team_id, + "user_id": user_id, + "master": master, + "role": role, + "api_key_present": api_key_present, + "inheritance": inheritance, + } + } + ) + ) diff --git a/litellm/_auth/model_groups.py b/litellm/_auth/model_groups.py new file mode 100644 index 00000000000..511325b8dee --- /dev/null +++ b/litellm/_auth/model_groups.py @@ -0,0 +1,46 @@ +from dataclasses import asdict, dataclass +from typing import Final, Literal + +from pydantic import TypeAdapter + +from litellm.rust_bridge import _native + + +@dataclass(frozen=True, slots=True) +class GroupResources: + assigned_team_ids: tuple[str, ...] + assigned_key_ids: tuple[str, ...] + resources: tuple[str, ...] + + +@dataclass(frozen=True, slots=True) +class GroupLookup: + kind: Literal["Found", "Missing", "Failed"] + group: GroupResources | None = None + + +@dataclass(frozen=True, slots=True) +class ResourceGroupFacts: + subject_present: bool + database_present: bool + cache_present: bool + group_ids: tuple[str, ...] + team_id: str | None + key_id: str | None + check_db_only: bool = False + strict_errors: bool = False + loaded: tuple[GroupLookup, ...] = () + + +@dataclass(frozen=True, slots=True) +class ResourceGroupDecision: + kind: Literal["Read", "Raise", "Complete"] + index: int = 0 + resources: tuple[str, ...] = () + + +_DECISION: Final = TypeAdapter(ResourceGroupDecision) + + +def resource_group_decision(facts: ResourceGroupFacts) -> ResourceGroupDecision: + return _DECISION.validate_python(_native.request_auth_model_groups(asdict(facts))) diff --git a/litellm/_auth/org_routes.py b/litellm/_auth/org_routes.py new file mode 100644 index 00000000000..ec519cb3981 --- /dev/null +++ b/litellm/_auth/org_routes.py @@ -0,0 +1,51 @@ +from dataclasses import asdict, dataclass +from typing import Final, Literal, TypeAlias + +from pydantic import TypeAdapter + +from litellm.rust_bridge import _native + + +@dataclass(frozen=True, slots=True) +class OrganizationMembership: + organization_id: str | None + role: str | None + + +@dataclass(frozen=True, slots=True) +class OrganizationRouteFacts: + route: str + user_present: bool + user_role: str | None + memberships: tuple[OrganizationMembership, ...] | None + organization_id: str | None + org_admin_routes: tuple[str, ...] + + +OrgRouteDenial: TypeAlias = Literal[ + "CreateOrganization", + "NoMemberships", + "MissingOrganization", + "MissingRole", + "WrongRole", + "TeamMissingOrganization", + "TeamWrongRole", +] + + +@dataclass(frozen=True, slots=True) +class OrganizationRouteDecision: + denial: OrgRouteDenial | None + organization_role: str | None + organization_ids: tuple[str, ...] + + +_DECISION: Final = TypeAdapter(OrganizationRouteDecision) + + +def organization_route(facts: OrganizationRouteFacts) -> OrganizationRouteDecision: + return _DECISION.validate_python(_native.request_auth_org_route(asdict(facts))) + + +def user_is_org_admin(memberships: tuple[OrganizationMembership, ...], organizations: tuple[str, ...]) -> bool: + return _native.request_auth_org_admin(tuple(asdict(item) for item in memberships), organizations) diff --git a/litellm/_auth/routes.py b/litellm/_auth/routes.py new file mode 100644 index 00000000000..1f9501b4844 --- /dev/null +++ b/litellm/_auth/routes.py @@ -0,0 +1,138 @@ +from collections.abc import Mapping +from dataclasses import asdict, dataclass, field +from typing import Final, Literal, TypeAlias + +from pydantic import TypeAdapter + +from litellm.rust_bridge import _native + + +@dataclass(frozen=True, slots=True) +class RouteCatalog: + groups: Mapping[str, tuple[str, ...]] = field(default_factory=dict[str, tuple[str, ...]]) + viewer_blocked: tuple[str, ...] = () + viewer_write_blocked: tuple[str, ...] = () + self_credentials: tuple[tuple[str, str], ...] = () + managed_models: tuple[str, ...] = () + managed_paths: tuple[str, ...] = () + managed_realtime: tuple[str, ...] = () + managed_live: tuple[str, ...] = () + managed_mcp: tuple[str, ...] = () + unbilled: tuple[str, ...] = () + + +@dataclass(frozen=True, slots=True) +class RouteContext: + route: str + method: str | None = None + catalog: RouteCatalog = field(default_factory=RouteCatalog) + registered: bool = False + registered_auth: bool | None = None + configured_eu_jev: bool = False + + +@dataclass(frozen=True, slots=True) +class PassThroughFacts: + key_allowed: tuple[str, ...] = () + team_allowed: tuple[str, ...] = () + denied: tuple[str, ...] = () + forwarded: tuple[str, ...] = () + jwt_team_routes: tuple[str, ...] = () + + +@dataclass(frozen=True, slots=True) +class VirtualRouteFacts: + context: RouteContext + allowed_routes: tuple[str, ...] | None + passthrough: PassThroughFacts = field(default_factory=PassThroughFacts) + password_reset_required: bool = False + + +@dataclass(frozen=True, slots=True) +class ViewerFacts: + context: RouteContext + request_keys: tuple[str, ...] = () + + +@dataclass(frozen=True, slots=True) +class NonAdminFacts: + viewer: ViewerFacts + role: str | None = None + custom_admin_routes: tuple[str, ...] = () + premium: bool = False + query_user_id: str | None = None + token_user_id: str | None = None + permissions: tuple[str, ...] = () + organization_ids: tuple[str, ...] = () + admin_organization_ids: tuple[str, ...] = () + team_service_account: bool = False + allowed_routes: tuple[str, ...] | None = None + passthrough: PassThroughFacts = field(default_factory=PassThroughFacts) + + +RouteDenial: TypeAlias = Literal[ + "VirtualRoute", + "PasswordReset", + "PassThrough", + "DeniedPassThrough", + "CustomAdmin", + "UserInfo", + "AdminOnly", + "ViewerInference", + "ViewerWrite", + "ViewerParameter", +] + + +@dataclass(frozen=True, slots=True) +class RouteDecision: + allowed: bool + denial: RouteDenial | None = None + detail: str | None = None + + +_DECISION: Final = TypeAdapter(RouteDecision) + + +def match_route( + route: str, + patterns: tuple[str, ...], + mode: Literal["Access", "Template", "Prefix", "Wildcard", "Denied", "Jwt"] = "Access", +) -> bool: + return _DECISION.validate_python( + _native.request_auth_route_access({"Match": {"route": route, "patterns": patterns, "mode": mode}}) + ).allowed + + +def classify_route( + context: RouteContext, kind: Literal["Llm", "Unbilled", "Discovery", "SelfCredential", "Azure", "Managed"] +) -> bool: + return _DECISION.validate_python( + _native.request_auth_route_access({"Classify": {"context": asdict(context), "kind": kind}}) + ).allowed + + +def virtual_route(facts: VirtualRouteFacts) -> RouteDecision: + return _DECISION.validate_python(_native.request_auth_route_access({"Virtual": asdict(facts)})) + + +def non_admin_route(facts: NonAdminFacts) -> RouteDecision: + return _DECISION.validate_python(_native.request_auth_route_access({"NonAdmin": asdict(facts)})) + + +def viewer_route(facts: ViewerFacts) -> RouteDecision: + return _DECISION.validate_python(_native.request_auth_route_access({"Viewer": asdict(facts)})) + + +def passthrough_route(context: RouteContext, facts: PassThroughFacts, *, required: bool = False) -> RouteDecision: + return _DECISION.validate_python( + _native.request_auth_route_access( + {"PassThrough": {"context": asdict(context), "facts": asdict(facts), "required": required}} + ) + ) + + +def denied_passthrough_route(route: str, facts: PassThroughFacts) -> RouteDecision: + return _DECISION.validate_python( + _native.request_auth_route_access({"DeniedPassThrough": {"route": route, "facts": asdict(facts)}}) + ) diff --git a/litellm/proxy/auth/fallback_access_adapter.py b/litellm/proxy/auth/fallback_access_adapter.py new file mode 100644 index 00000000000..f344d6d57b6 --- /dev/null +++ b/litellm/proxy/auth/fallback_access_adapter.py @@ -0,0 +1,111 @@ +from dataclasses import replace +from typing import Final + +from litellm._auth.fallback_access import FallbackAuthorizationFacts, GroupedModelScope, fallback_authorization +from litellm._auth.model_access import key_model_grants +from litellm.proxy._types import LiteLLM_ProjectTable, LiteLLM_TeamMembership, LiteLLM_TeamTable, UserAPIKeyAuth +from litellm.proxy.auth.model_access_adapter import object_model_grants, project_model_facts +from litellm.proxy.auth.model_group_adapter import get_authorized_resources_from_key_access_groups +from litellm.repositories.prisma_protocols import DatabaseClient +from litellm.router_api import RegistryReader + + +async def load_fallback_authorization_facts( + model: str, + valid_token: UserAPIKeyAuth, + llm_router: RegistryReader | None, + prisma_client: DatabaseClient | None = None, + team_membership: LiteLLM_TeamMembership | None = None, + project_object: LiteLLM_ProjectTable | None = None, + refuse_agent_keys: bool = False, + team_object: LiteLLM_TeamTable | None = None, +) -> FallbackAuthorizationFacts: + from litellm.proxy.auth.auth_checks import key_model_aliases_for_auth_check + + aliases: Final = key_model_aliases_for_auth_check(valid_token) + key_grants: Final = key_model_grants( + object_model_grants(valid_token), valid_token.team_id, tuple(valid_token.team_models or ()) + ) + member_grants: Final = ( + tuple(team_membership.litellm_budget_table.allowed_models or ()) + if team_membership is not None and team_membership.litellm_budget_table is not None + else () + ) + facts: Final = FallbackAuthorizationFacts( + key=GroupedModelScope( + project_model_facts( + model, llm_router, key_grants, valid_token.team_model_aliases, valid_token.team_id, aliases, "key" + ), + tuple(valid_token.access_group_ids or ()), + ), + refuse_agent_keys=refuse_agent_keys, + agent_id=valid_token.agent_id, + team=GroupedModelScope( + project_model_facts( + model, + llm_router, + team_object.models, + valid_token.team_model_aliases, + team_object.team_id, + aliases, + "team", + ), + tuple(team_object.access_group_ids or ()), + ) + if team_object is not None + else None, + embedded_team=project_model_facts( + model, + llm_router, + valid_token.team_models or (), + valid_token.team_model_aliases, + valid_token.team_id, + aliases, + "team", + ) + if team_object is None + else None, + member=project_model_facts( + model, llm_router, member_grants, team_id=valid_token.team_id, key_model_aliases=aliases, object_type="team" + ), + project=project_model_facts( + model, + llm_router, + project_object.models, + team_id=project_object.team_id, + key_model_aliases=aliases, + object_type="project", + ) + if project_object is not None + else None, + ) + return await _load_groups(facts, valid_token, team_object, prisma_client) + + +async def _load_groups( + facts: FallbackAuthorizationFacts, + token: UserAPIKeyAuth, + team: LiteLLM_TeamTable | None, + prisma: DatabaseClient | None, +) -> FallbackAuthorizationFacts: + from litellm.proxy.auth.auth_checks import get_models_from_access_groups + + decision: Final = fallback_authorization(facts) + match decision.kind: + case "Allow" | "Deny": + return facts + case "ReadKeyGroups": + models: Final = await get_models_from_access_groups(facts.key.group_ids, prisma_client=prisma) + return await _load_groups( + replace(facts, key=replace(facts.key, group_models=tuple(models))), token, team, prisma + ) + case "ReadTeamGroups": + if facts.team is None: + raise RuntimeError("fallback requested missing team") + team_models: Final = await get_models_from_access_groups(facts.team.group_ids, prisma_client=prisma) + return await _load_groups( + replace(facts, team=replace(facts.team, group_models=tuple(team_models))), token, team, prisma + ) + case "ReadAssignedGroups": + assigned: Final = await get_authorized_resources_from_key_access_groups(token, team, "access_model_names") + return await _load_groups(replace(facts, assigned_models=tuple(assigned)), token, team, prisma) diff --git a/litellm/proxy/auth/model_access_adapter.py b/litellm/proxy/auth/model_access_adapter.py new file mode 100644 index 00000000000..1973a8bf63a --- /dev/null +++ b/litellm/proxy/auth/model_access_adapter.py @@ -0,0 +1,329 @@ +from collections.abc import Mapping, Sequence +from dataclasses import replace +from typing import Final, Literal + +from fastapi import HTTPException +from pydantic import BaseModel + +import litellm +from litellm._auth.model_access import ( + ModelAccessDecision, + ModelAccessFacts, + ModelAliases, + ModelObject, + ModelProvider, + ModelRecord, + ModelRegistry, + grouped_model_access, + key_model_grants, + model_access, + model_candidates, + user_model_access, +) +from litellm.constants import DEFAULT_MAX_RECURSE_DEPTH +from litellm.proxy._types import ( + LiteLLM_EndUserTable, + LiteLLM_OrganizationTable, + LiteLLM_ProjectTable, + LiteLLM_TeamTable, + LiteLLM_UserTable, + ModelAccessDeniedProxyException, + ProxyErrorTypes, + UserAPIKeyAuth, +) +from litellm.proxy.auth.model_access_denied import ( + customer_model_access_denied_client_message, + model_access_denied_client_message, +) +from litellm.repositories.prisma_protocols import DatabaseClient +from litellm.router_api import RegistryReader +from litellm.router_strategy.complexity_router.context_compaction import native_compaction_parent + + +class ModelLists(BaseModel, frozen=True): + models: tuple[str, ...] = () + + +def object_model_grants(source: object) -> tuple[str, ...]: + return ModelLists.model_validate(source, from_attributes=True).models + + +def _provider(model: str) -> ModelProvider | None: + try: + stripped, provider, _, _ = litellm.get_llm_provider(model=model) + return ModelProvider(stripped, provider) + except Exception: + return None + + +def _record(model: str, router: RegistryReader | None, team_id: str | None) -> ModelRecord: + deployment: Final = router.registry().deployments(model, source="first_in_group") if router is not None else None + return ModelRecord( + access_groups=tuple(router.registry().access_groups(model_name=model, team_id=team_id)) + if router is not None + else (), + provider=_provider(model), + deployment_team=deployment.model_info.team_id if deployment is not None else None, + deployment_public_name=deployment.model_info.team_public_model_name if deployment is not None else None, + ) + + +def project_model_facts( + model: str | Sequence[str], + llm_router: RegistryReader | None, + models: Sequence[str], + team_model_aliases: Mapping[str, str] | None = None, + team_id: str | None = None, + key_model_aliases: Mapping[str, str] | None = None, + object_type: ModelObject = "user", + fallback_depth: int = 0, +) -> ModelAccessFacts: + requested: Final = (model,) if isinstance(model, str) else tuple(model) + aliases: Final = ModelAliases( + team=dict(team_model_aliases or {}), key=dict(key_model_aliases or {}), global_=dict(litellm.model_alias_map) + ) + names: Final = tuple(dict.fromkeys((*requested, *aliases.team.values()))) + registry: Final = ModelRegistry( + present=llm_router is not None, + names=tuple(llm_router.registry().names()) if llm_router is not None else (), + aliases={ + name: target + for name in names + if name in llm_router.registry().aliases() + and (target := llm_router.registry().resolve(name, kind="alias")) is not None + } + if llm_router is not None + else {}, + records={name: _record(name, llm_router, team_id) for name in names}, + compaction_parents={name: parent for name in names if (parent := native_compaction_parent(name)) is not None}, + ) + initial: Final = ModelAccessFacts( + requested=requested, + grants=tuple(models), + team_id=team_id, + aliases=aliases, + registry=registry, + object_type=object_type, + fallback_depth=fallback_depth, + max_depth=DEFAULT_MAX_RECURSE_DEPTH, + is_list=not isinstance(model, str), + ) + candidates: Final = model_candidates(replace(initial, requested=names)) + return replace( + initial, + registry=replace( + registry, + records={ + **registry.records, + **{name: _record(name, llm_router, team_id) for name in candidates if name not in registry.records}, + }, + ), + ) + + +def raise_model_denial( + decision: ModelAccessDecision, + requested: str | Sequence[str], + *, + user_id: str | None = None, + team_id: str | None = None, + teams: Sequence[str] | None = None, + member_models: Sequence[str] | None = None, +) -> Literal[True]: + model: Final = requested if isinstance(requested, str) else list(requested) + match decision.kind: + case "Allow": + return True + case "Depth": + raise Exception( + f"Unable to parse model, max fallback depth exceeded - received model: {decision.model if decision.model is not None else model}" + ) + case "NoAgentModels": + raise HTTPException(403, "This agent has no model grants") + case "ReadGroups": + raise RuntimeError("model grant lookup was not answered") + case "Deny" | "NoDefaultModels" | "EmptyAgentCeiling" | "PersonalTeam": + error_model: Final = decision.model if decision.model is not None else model + object_type: Final = decision.object_type + message: Final = ( + customer_model_access_denied_client_message(error_model) + if object_type == "customer" + else model_access_denied_client_message(error_model) + ) + internal: Final = ( + f"Team member not allowed to access model. User={user_id}, Team={team_id}, Model={model}. Allowed member models = {list(member_models)}" + if member_models is not None + else ( + f"User not allowed to access model. No default model access, only team models allowed. Tried to access {model}" + if decision.kind == "NoDefaultModels" + else ( + f"agent {user_id} access groups grant no models" + if decision.kind == "EmptyAgentCeiling" + else ( + f"Personal key model access is derived from the owner's teams. User={user_id}, teams={list(teams) if teams is not None else None}, model={error_model}" + if decision.kind == "PersonalTeam" + else ( + f"{object_type} not allowed to access model. This {object_type} can only access models={list(decision.grants)}. Tried to access {error_model}" + ) + ) + ) + ) + ) + error_type: Final = ( + ProxyErrorTypes.team_model_access_denied + if member_models is not None + else ( + ProxyErrorTypes.key_model_access_denied + if decision.kind in ("NoDefaultModels", "PersonalTeam") + else ( + ProxyErrorTypes.agent_model_access_denied + if decision.kind == "EmptyAgentCeiling" + else ProxyErrorTypes.get_model_access_error_type_for_object(object_type) + ) + ) + ) + raise ModelAccessDeniedProxyException( + message=message, internal_message=internal, type=error_type, param="model", code=403 + ) + + +def can_object_call_model( + model: str | Sequence[str], + llm_router: RegistryReader | None, + models: Sequence[str], + team_model_aliases: Mapping[str, str] | None = None, + team_id: str | None = None, + key_model_aliases: Mapping[str, str] | None = None, + object_type: ModelObject = "user", + fallback_depth: int = 0, +) -> Literal[True]: + facts: Final = project_model_facts( + model, llm_router, models, team_model_aliases, team_id, key_model_aliases, object_type, fallback_depth + ) + return raise_model_denial(model_access(facts), model) + + +async def _grouped_model_access( + facts: ModelAccessFacts, + group_ids: Sequence[str], + prisma_client: DatabaseClient | None, + *, + merge: bool, +) -> ModelAccessDecision: + from litellm.proxy.auth.auth_checks import get_models_from_access_groups + + decision: Final = grouped_model_access(facts, tuple(group_ids), merge=merge) + if decision.kind != "ReadGroups": + return decision + models: Final = await get_models_from_access_groups(list(group_ids), prisma_client=prisma_client) + return grouped_model_access(facts, tuple(group_ids), tuple(models), merge=merge) + + +async def can_key_call_model( + model: str | Sequence[str], + llm_model_list: Sequence[object] | None, + valid_token: UserAPIKeyAuth, + llm_router: RegistryReader | None, + prisma_client: DatabaseClient | None = None, +) -> Literal[True]: + from litellm.proxy.auth.auth_checks import key_model_aliases_for_auth_check + + grants: Final = key_model_grants( + object_model_grants(valid_token), valid_token.team_id, tuple(valid_token.team_models or ()) + ) + facts: Final = project_model_facts( + model, + llm_router, + grants, + valid_token.team_model_aliases, + valid_token.team_id, + key_model_aliases_for_auth_check(valid_token), + "key", + ) + decision: Final = await _grouped_model_access(facts, valid_token.access_group_ids or (), prisma_client, merge=False) + return raise_model_denial(decision, model) + + +async def can_team_access_model( + model: str | Sequence[str], + team_object: LiteLLM_TeamTable | None, + llm_router: RegistryReader | None, + team_model_aliases: Mapping[str, str] | None = None, + key_model_aliases: Mapping[str, str] | None = None, + prisma_client: DatabaseClient | None = None, +) -> Literal[True]: + facts: Final = project_model_facts( + model, + llm_router, + team_object.models if team_object is not None else (), + team_model_aliases, + team_object.team_id if team_object is not None else None, + key_model_aliases, + "team", + ) + decision: Final = await _grouped_model_access( + facts, (team_object.access_group_ids or ()) if team_object is not None else (), prisma_client, merge=True + ) + return raise_model_denial(decision, model) + + +def can_org_access_model( + model: str, + org_object: LiteLLM_OrganizationTable | None, + llm_router: RegistryReader | None, + team_model_aliases: Mapping[str, str] | None = None, +) -> Literal[True]: + return can_object_call_model( + model, llm_router, org_object.models if org_object is not None else (), team_model_aliases, object_type="org" + ) + + +def can_project_access_model( + model: str | Sequence[str], + project_object: LiteLLM_ProjectTable, + llm_router: RegistryReader | None, + key_model_aliases: Mapping[str, str] | None = None, +) -> Literal[True]: + return can_object_call_model( + model, + llm_router, + project_object.models, + team_id=project_object.team_id, + key_model_aliases=key_model_aliases, + object_type="project", + ) + + +def can_customer_access_model( + model: str | Sequence[str], + end_user_object: LiteLLM_EndUserTable, + llm_router: RegistryReader | None, + valid_token: UserAPIKeyAuth | None, +) -> Literal[True]: + from litellm.proxy.auth.auth_checks import key_model_aliases_for_auth_check, team_model_aliases_for_auth_check + + facts: Final = project_model_facts( + model, + llm_router, + end_user_object.models or (), + team_model_aliases_for_auth_check(valid_token) if valid_token is not None else None, + valid_token.team_id if valid_token is not None else None, + key_model_aliases_for_auth_check(valid_token), + "customer", + ) + return raise_model_denial(model_access(facts, kind="Customer"), model) + + +async def can_user_call_model( + model: str | Sequence[str], + llm_router: RegistryReader | None, + user_object: LiteLLM_UserTable | None, + key_model_aliases: Mapping[str, str] | None = None, +) -> Literal[True]: + facts: Final = project_model_facts( + model, + llm_router, + object_model_grants(user_object) if user_object is not None else (), + key_model_aliases=key_model_aliases, + ) + return raise_model_denial(user_model_access(facts, present=user_object is not None), model) diff --git a/litellm/proxy/auth/model_group_adapter.py b/litellm/proxy/auth/model_group_adapter.py new file mode 100644 index 00000000000..4683989b3ed --- /dev/null +++ b/litellm/proxy/auth/model_group_adapter.py @@ -0,0 +1,91 @@ +from dataclasses import dataclass, replace +from typing import Final, Literal, TypeAlias + +from litellm._auth.model_groups import GroupLookup, GroupResources, ResourceGroupFacts, resource_group_decision +from litellm.proxy._types import LiteLLM_TeamTable, UserAPIKeyAuth + +ResourceField: TypeAlias = Literal[ + "access_model_names", "access_mcp_server_ids", "access_agent_ids", "access_skill_names" +] + + +@dataclass(frozen=True, slots=True) +class GroupRead: + lookup: GroupLookup + error: Exception | None = None + + +async def get_authorized_resources_from_key_access_groups( + valid_token: UserAPIKeyAuth | None, + team_object: LiteLLM_TeamTable | None, + resource_field: ResourceField, + check_db_only: bool = False, + strict_errors: bool = False, +) -> list[str]: # mutable-ok: retain the legacy public return contract + from litellm.proxy.proxy_server import prisma_client, user_api_key_cache + + facts: Final = ResourceGroupFacts( + subject_present=valid_token is not None, + database_present=prisma_client is not None, + cache_present=_present(user_api_key_cache), + group_ids=tuple(valid_token.access_group_ids or ()) if valid_token is not None else (), + team_id=(valid_token.team_id if valid_token is not None else None) + or (team_object.team_id if team_object is not None else None), + key_id=valid_token.token if valid_token is not None else None, + check_db_only=check_db_only, + strict_errors=strict_errors, + ) + return list(set(await _drive(facts, resource_field, ()))) + + +async def _read(group_id: str, resource_field: ResourceField, check_db_only: bool) -> GroupRead: + from litellm.proxy.auth.auth_checks import AccessGroupNotFoundError, get_access_object + from litellm.proxy.proxy_server import prisma_client, proxy_logging_obj, user_api_key_cache + + try: + group: Final = await get_access_object( + access_group_id=group_id, + prisma_client=prisma_client, + user_api_key_cache=user_api_key_cache, + proxy_logging_obj=proxy_logging_obj, + check_db_only=check_db_only, + ) + resources: Final = { + "access_model_names": group.access_model_names, + "access_mcp_server_ids": group.access_mcp_server_ids, + "access_agent_ids": group.access_agent_ids, + "access_skill_names": group.access_skill_names, + }[resource_field] + return GroupRead( + GroupLookup( + "Found", + GroupResources( + tuple(group.assigned_team_ids or ()), tuple(group.assigned_key_ids or ()), tuple(resources or ()) + ), + ) + ) + except AccessGroupNotFoundError as error: + return GroupRead(GroupLookup("Missing"), error) + except Exception as error: + return GroupRead(GroupLookup("Failed"), error) + + +async def _drive( + facts: ResourceGroupFacts, resource_field: ResourceField, reads: tuple[GroupRead, ...] +) -> tuple[str, ...]: + decision: Final = resource_group_decision(facts) + match decision.kind: + case "Complete": + return decision.resources + case "Raise": + error: Final = reads[decision.index].error + if error is None: + raise RuntimeError("missing access group lookup failure") + raise error + case "Read": + result: Final = await _read(facts.group_ids[decision.index], resource_field, facts.check_db_only) + return await _drive(replace(facts, loaded=(*facts.loaded, result.lookup)), resource_field, (*reads, result)) + + +def _present(value: object) -> bool: + return value is not None diff --git a/litellm/proxy/auth/org_route_adapter.py b/litellm/proxy/auth/org_route_adapter.py new file mode 100644 index 00000000000..eedbbeb5c19 --- /dev/null +++ b/litellm/proxy/auth/org_route_adapter.py @@ -0,0 +1,84 @@ +from collections.abc import Mapping +from typing import Final + +from pydantic import TypeAdapter + +from litellm._auth.org_routes import ( + OrganizationMembership, + OrganizationRouteFacts, + organization_route, +) +from litellm._auth.org_routes import ( + user_is_org_admin as native_org_admin, +) +from litellm.proxy._types import LiteLLM_UserTable, LiteLLMRoutes, ProxyErrorTypes, ProxyException + +_STRINGS: Final = TypeAdapter(tuple[str, ...]) + + +def memberships(user: LiteLLM_UserTable | None) -> tuple[OrganizationMembership, ...] | None: + return ( + tuple(OrganizationMembership(item.organization_id, item.user_role) for item in user.organization_memberships) + if user is not None and user.organization_memberships is not None + else None + ) + + +def user_is_org_admin(request_data: Mapping[str, object], user_object: LiteLLM_UserTable | None = None) -> bool: + singular: Final = request_data.get("organization_id") + plural: Final = request_data.get("organizations") + return native_org_admin( + memberships(user_object) or (), + ( + *((singular,) if isinstance(singular, str) else ()), + *(_STRINGS.validate_python(plural) if isinstance(plural, list) else ()), + ), + ) + + +def organization_role_based_access_check( + request_body: Mapping[str, object], user_object: LiteLLM_UserTable | None, route: str +) -> None: + passed: Final = request_body.get("organization_id") + organization_id: Final = passed if isinstance(passed, str) else None + role: Final = user_object.user_role if user_object is not None else None + decision: Final = organization_route( + OrganizationRouteFacts( + route, + user_object is not None, + role, + memberships(user_object), + organization_id, + tuple(LiteLLMRoutes.org_admin_only_routes.value), + ) + ) + messages: Final = { + "CreateOrganization": (f"Only proxy admins can create new organizations. You are {role}", "user_role"), + "NoMemberships": ( + f"Tried to access route={route} but you are not a member of any organization. Please contact the proxy admin to request access.", + "organization_id", + ), + "MissingOrganization": ( + "Passed organization_id is None, please pass an organization_id in your request", + "organization_id", + ), + "MissingRole": ( + f"You do not have a role within the selected organization. Passed organization_id: {organization_id}. Please contact the organization admin to request access.", + "organization_id", + ), + "WrongRole": ( + f"You do not have the required role to perform {route} in Organization {organization_id}. Your role is {decision.organization_role} in Organization {organization_id}", + "user_role", + ), + "TeamMissingOrganization": ( + f"Passed organization_id is None, please specify the organization_id in your request. You are part of multiple organizations: {list(decision.organization_ids)}", + "organization_id", + ), + "TeamWrongRole": ( + f"You do not have the required role to call {route}. Your role is {decision.organization_role} in Organization {organization_id}", + "user_role", + ), + } + if decision.denial is not None: + message, param = messages[decision.denial] + raise ProxyException(message=message, type=ProxyErrorTypes.auth_error.value, param=param, code=401) diff --git a/litellm/proxy/auth/route_checks.py b/litellm/proxy/auth/route_checks.py index 125bfab4edf..16180292870 100644 --- a/litellm/proxy/auth/route_checks.py +++ b/litellm/proxy/auth/route_checks.py @@ -1,11 +1,11 @@ -import itertools -import re from collections.abc import Collection, Iterable, Mapping from typing import Final, cast from fastapi import HTTPException, Request, status from litellm._logging import verbose_proxy_logger +from litellm._auth import routes +from litellm.proxy.auth import route_policy_adapter from litellm.proxy._types import ( MODEL_LIST_ROUTES, UI_TEAM_ID, @@ -141,120 +141,7 @@ class RouteChecks: valid_token: UserAPIKeyAuth, request: Request | None = None, ) -> bool: - """ - Raises Exception if Virtual Key is not allowed to call the route - """ - - # Only check if valid_token.allowed_routes is set and is a list with at least one item - if valid_token.allowed_routes is None: - return True - if not isinstance(valid_token.allowed_routes, list): - return True - if len(valid_token.allowed_routes) == 0: - return True - - denied_auth_enforced_pass_through_route = False - - # explicit check for allowed routes (exact match or prefix match) - for allowed_route in valid_token.allowed_routes: - if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route): - return True - - ## check if 'allowed_route' is a field name in LiteLLMRoutes - if any(allowed_route in LiteLLMRoutes._member_names_ for allowed_route in valid_token.allowed_routes): - for allowed_route in valid_token.allowed_routes: - if allowed_route in LiteLLMRoutes._member_names_: - if RouteChecks.check_route_access( - route=route, - allowed_routes=LiteLLMRoutes[allowed_route].value, - ): - if ( - allowed_route in _AUTH_ENFORCED_PASS_THROUGH_ROUTE_GROUPS - and RouteChecks.is_auth_enforced_pass_through_route( - route=route, - method=RouteChecks.get_request_method(request=request), - ) - ): - if RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token): - return True - denied_auth_enforced_pass_through_route = True - else: - return True - - ################################################ - # For llm_api_routes, also check registered pass-through endpoints - ################################################ - if allowed_route in _LLM_API_ROUTE_GROUPS: - if route == "/auto_router/session" and RouteChecks.get_request_method(request) == "GET": - return True - - from litellm.proxy.pass_through_endpoints.pass_through_endpoints import ( - InitPassThroughEndpointHelpers, - ) - - if InitPassThroughEndpointHelpers.is_registered_pass_through_route(route=route): - if RouteChecks.is_auth_enforced_pass_through_route( - route=route, - method=RouteChecks.get_request_method(request=request), - ): - if RouteChecks.check_passthrough_route_access( - route=route, user_api_key_dict=valid_token - ): - return True - denied_auth_enforced_pass_through_route = True - else: - return True - - # Method-aware carve-out: allow GET on the two - # read-only MCP-server discovery endpoints - # (`/v1/mcp/server` and `/v1/mcp/server/{server_id}`) - # so virtual keys with allowed_routes=["llm_api_routes"] - # can list/inspect MCP servers. The GET handlers in - # mcp_management_endpoints.py sanitize the response - # for restricted virtual keys (stripping url, - # headers, env, credentials). POST/PUT/DELETE on - # these paths are admin-only management writes and - # are intentionally not covered. - if allowed_route == "llm_api_routes" and RouteChecks._is_get_mcp_server_discovery_route( - route=route, request=request - ): - return True - - # Agent registry CRUD moved from llm_api_routes into - # management_routes so DISABLE_LLM_API_ENDPOINTS stops - # blocking it. Keys configured with - # allowed_routes=["llm_api_routes"] before that split - # could reach these paths, so keep them reachable here; - # the handlers in agent_endpoints/endpoints.py still - # enforce proxy-admin on writes and scope reads by role. - if allowed_route == "llm_api_routes" and RouteChecks.check_route_access( - route=route, - allowed_routes=LiteLLMRoutes.agent_management_routes.value, - ): - return True - - # check if wildcard pattern is allowed - for allowed_route in valid_token.allowed_routes: - if RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route): - return True - - if denied_auth_enforced_pass_through_route: - raise RouteChecks._auth_pass_through_denied_exception(route=route) - - if valid_token.metadata.get("password_reset_required") is True: - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=( - "This account's password must be changed before the session can be used: " - "it was either found in a known data breach or set by an admin. " - "Change it via POST /user/password/change (UI: /ui/change-password), then log in again." - ), - ) - - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"Virtual key is not allowed to call this route. Only allowed to call routes: {valid_token.allowed_routes}. Tried to call route: {route}", - ) + return route_policy_adapter.check_virtual_route(route, valid_token, request) @staticmethod def _mask_user_id(user_id: str) -> str: @@ -318,109 +205,7 @@ class RouteChecks: valid_token: UserAPIKeyAuth, request_data: dict, ): - """ - Checks if Non Proxy Admin User is allowed to access the route - """ - - # Check user has defined custom admin routes - RouteChecks.custom_admin_only_route_check( - route=route, - ) - - if RouteChecks.is_auth_enforced_pass_through_route( - route=route, - method=RouteChecks.get_request_method(request=request), - ): - RouteChecks._require_auth_pass_through_access( - route=route, - valid_token=valid_token, - jwt_team_allowed_routes=RouteChecks._jwt_team_allowed_routes(valid_token=valid_token), - ) - elif RouteChecks.is_llm_api_route(route=route): - pass - elif RouteChecks.is_info_route(route=route): - # check if user allowed to call an info route - if route == "/key/info": - # handled by function itself - pass - elif route == "/user/info": - # check if user can access this route - query_params: Final = request.query_params - user_id: Final = query_params.get("user_id") - verbose_proxy_logger.debug("user_id: %s & valid_token.user_id: %s", user_id, valid_token.user_id) - if ( - user_id - and user_id != valid_token.user_id - and _user_role != LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value - ): - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"key not allowed to access this user's info. user_id={user_id}, key's user_id={valid_token.user_id}", - ) - elif route == "/v2/user/info": - # handled by the endpoint itself (full RBAC in handler) - pass - elif route == "/model/info": - # /model/info just shows models user has access to - pass - elif route == "/team/info": - pass # handled by function itself - elif ( - route in LiteLLMRoutes.global_spend_tracking_routes.value - and getattr(valid_token, "permissions", None) is not None - and "get_spend_routes" in getattr(valid_token, "permissions", []) - ): - pass - elif route == "/lens" or route.startswith("/lens/"): - pass # Lens authorizes the delegated role, including its POST-based read endpoints. - elif _user_role == LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value: - RouteChecks._check_proxy_admin_viewer_access( - route=route, - _user_role=_user_role, - request_data=request_data, - request=request, - ) - elif ( - _user_role == LitellmUserRoles.INTERNAL_USER.value - and ( - RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.internal_user_routes.value) - or RouteChecks.is_self_scoped_credential_route(route=route, request=request) - ) - or user_is_org_admin(request_data=request_data, user_object=user_obj) - and RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.org_admin_allowed_routes.value) - or _user_role == LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value - and RouteChecks.check_route_access( - route=route, - allowed_routes=LiteLLMRoutes.internal_user_view_only_routes.value, - ) - or RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.self_managed_routes.value) - ): - pass - elif route.startswith("/v1/mcp/") or route.startswith("/mcp-rest/"): - pass # authN/authZ handled by api itself - elif RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token) or ( - valid_token.is_team_service_account - and RouteChecks.check_route_access( - route=route, allowed_routes=LiteLLMRoutes.team_service_account_key_routes.value - ) - ): - pass - elif valid_token.allowed_routes is not None: - # check if route is in allowed_routes (exact match or prefix match) - route_allowed = False - for allowed_route in valid_token.allowed_routes: - if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route): - route_allowed = True - break - - if RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route): - route_allowed = True - break - - if not route_allowed: - RouteChecks._raise_admin_only_route_exception(user_obj=user_obj, route=route) - else: - RouteChecks._raise_admin_only_route_exception(user_obj=user_obj, route=route) + return route_policy_adapter.check_non_admin_route(user_obj, _user_role, route, request, valid_token, request_data) @staticmethod def custom_admin_only_route_check(route: str): @@ -441,73 +226,11 @@ class RouteChecks: @staticmethod def is_unbilled_route(route: str) -> bool: - resource, _, action = route.rsplit("/", 1)[-1].partition(":") - return route in _UNBILLED_ROUTES or resource in _TOKEN_COUNTING_SEGMENTS or action == _TOKEN_COUNTING_ACTION + return route_policy_adapter.classify(route, "Unbilled") @staticmethod def is_llm_api_route(route: str) -> bool: - """ - Helper to checks if provided route is an OpenAI route - - - Returns: - - True: if route is an OpenAI route - - False: if route is not an OpenAI route - """ - # Ensure route is a string before performing checks - if not isinstance(route, str): - return False - - if route in LiteLLMRoutes.openai_routes.value: - return True - - if route in LiteLLMRoutes.anthropic_routes.value: - return True - - if route in LiteLLMRoutes.google_routes.value: - return True - - if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.mcp_inference_routes.value): - return True - - if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.agent_inference_routes.value): - return True - - if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.litellm_native_routes.value): - return True - - # fuzzy match routes like "/v1/threads/thread_49EIN5QF32s4mH20M7GFKdlZ" - # Check for routes with placeholders or wildcard patterns - for openai_route in LiteLLMRoutes.openai_routes.value: - # Replace placeholders with regex pattern - # placeholders are written as "/threads/{thread_id}" - if "{" in openai_route: - if RouteChecks._route_matches_pattern(route=route, pattern=openai_route): - return True - # Check for wildcard patterns like "/containers/*" - if RouteChecks.is_wildcard_pattern(pattern=openai_route): - if RouteChecks.route_matches_wildcard_pattern(route=route, pattern=openai_route): - return True - - # Check for Google routes with placeholders like "/v1beta/models/{model_name}:generateContent" - for google_route in LiteLLMRoutes.google_routes.value: - if "{" in google_route: - if RouteChecks._route_matches_pattern(route=route, pattern=google_route): - return True - - # Check for Anthropic routes with placeholders - for anthropic_route in LiteLLMRoutes.anthropic_routes.value: - if "{" in anthropic_route: - if RouteChecks._route_matches_pattern(route=route, pattern=anthropic_route): - return True - - if RouteChecks._is_azure_openai_route(route=route): - return True - - for _llm_passthrough_route in LiteLLMRoutes.mapped_pass_through_routes.value: - if route == _llm_passthrough_route or route.startswith(_llm_passthrough_route + "/"): - return True - return RouteChecks.is_builtin_eu_jev_decision_route(route=route) + return isinstance(route, str) and route_policy_adapter.classify(route, "Llm") @staticmethod def is_builtin_eu_jev_decision_route(route: str) -> bool: @@ -523,26 +246,7 @@ class RouteChecks: @staticmethod def _is_get_mcp_server_discovery_route(route: str, request: Request | None) -> bool: - """ - Returns True if `request` is a GET against one of the two read-only - MCP-server discovery paths: - - - GET `/v1/mcp/server` (list) - - GET `/v1/mcp/server/{server_id}` (single server, single segment) - - Multi-segment paths (`/v1/mcp/server/{id}/approve`, etc.) and any - non-GET method return False, so admin-only management writes on the - same path prefix are not reachable through this carve-out. - """ - if request is None or request.method.upper() != "GET": - return False - if route == "/v1/mcp/server": - return True - prefix: Final = "/v1/mcp/server/" - if not route.startswith(prefix): - return False - remainder: Final = route[len(prefix) :] - return bool(remainder) and "/" not in remainder + return route_policy_adapter.classify(route, "Discovery", RouteChecks.get_request_method(request)) @staticmethod def is_management_route(route: str) -> bool: @@ -567,67 +271,11 @@ class RouteChecks: @staticmethod def _is_azure_openai_route(route: str) -> bool: - """ - Check if route is a route from AzureOpenAI SDK client - - eg. - route='/openai/deployments/vertex_ai/gemini-1.5-flash/chat/completions' - """ - # Ensure route is a string before attempting regex matching - if not isinstance(route, str): - return False - # Add support for deployment and engine model paths - deployment_pattern: Final = r"^/openai/deployments/[^/]+/[^/]+/chat/completions$" - engine_pattern: Final = r"^/engines/[^/]+/chat/completions$" - - if re.match(deployment_pattern, route) or re.match(engine_pattern, route): - return True - return False + return isinstance(route, str) and route_policy_adapter.classify(route, "Azure") @staticmethod def _route_matches_pattern(route: str, pattern: str) -> bool: - """ - Check if route matches the pattern placed in proxy/_types.py - - Example: - - pattern: "/threads/{thread_id}" - - route: "/threads/thread_49EIN5QF32s4mH20M7GFKdlZ" - - returns: True - - - - pattern: "/key/{token_id}/regenerate" - - route: "/key/regenerate/82akk800000000jjsk" - - returns: False, pattern is "/key/{token_id}/regenerate" - """ - # Ensure route is a string before attempting regex matching - if not isinstance(route, str): - return False - - def _placeholder_to_regex(match: re.Match) -> str: - placeholder: Final = match.group(0).strip("{}") - if not placeholder.endswith(":path"): - return r"[^/]+" - # A ":path" placeholder takes whatever the router's own path - # converter takes, slashes and colons alike, so an id spelled with - # either (or both) still matches the template it was mounted under. - # - # Unless the template puts a ":" literal of its own after the - # placeholder: the Google routes end in ":generateContent" and - # friends, and there the value has to stop before that suffix - # rather than swallow it and match a different verb. - # - # "[\s\S]" rather than ".", because "." stops at a newline and the - # path converter does not: a %0A anywhere in the value would leave - # the route unmatched here while still reaching the handler, which - # turns this gate into a bypass for the lists built on it. - return r"[^:]+" if ":" in match.string[match.end() :] else r"[\s\S]+" - - pattern = re.sub(r"\{[^}]+\}", _placeholder_to_regex, pattern) - # Anchor the pattern to match the entire string - pattern = f"^{pattern}$" - if re.match(pattern, route): - return True - return False + return isinstance(route, str) and routes.match_route(route, (pattern,), "Template") @staticmethod def is_wildcard_pattern(pattern: str) -> bool: @@ -640,100 +288,15 @@ class RouteChecks: @staticmethod def route_matches_wildcard_pattern(route: str, pattern: str) -> bool: - """ - Check if route matches the wildcard pattern - - eg. - - pattern: "/scim/v2/*" - route: "/scim/v2/Users" - - returns: True - - pattern: "/scim/v2/*" - route: "/chat/completions" - - returns: False - - - pattern: "/scim/v2/*" - route: "/scim/v2/Users/123" - - returns: True - - """ - if pattern.endswith("*"): - # Get the prefix (everything before the wildcard) - prefix: Final = pattern[:-1] - return route.startswith(prefix) - else: - # If there's no wildcard, the pattern and route should match exactly - return route == pattern + return routes.match_route(route, (pattern,), "Wildcard") @staticmethod def _route_matches_allowed_route(route: str, allowed_route: str) -> bool: - """ - Check if route matches the allowed_route pattern. - Supports both exact match and prefix match. - - Examples: - - allowed_route="/fake-openai-proxy-6", route="/fake-openai-proxy-6" -> True (exact match) - - allowed_route="/fake-openai-proxy-6", route="/fake-openai-proxy-6/v1/chat/completions" -> True (prefix match) - - allowed_route="/fake-openai-proxy-6", route="/fake-openai-proxy-600" -> False (not a valid prefix) - - Args: - route: The actual route being accessed - allowed_route: The allowed route pattern - - Returns: - bool: True if route matches (exact or prefix), False otherwise - """ - # Exact match - if route == allowed_route: - return True - # Prefix match - ensure we add "/" to prevent false matches like /fake-openai-proxy-600 - if route.startswith(allowed_route + "/"): - return True - return False + return routes.match_route(route, (allowed_route,), "Prefix") @staticmethod def check_route_access(route: str, allowed_routes: Collection[str]) -> bool: - """ - Check if a route has access by checking both exact matches and patterns - - Args: - route (str): The route to check - allowed_routes (Sequence): Allowed routes/patterns - - Returns: - bool: True if route is allowed, False otherwise - """ - ######################################################### - # exact match route is in allowed_routes - ######################################################### - if route in allowed_routes: - return True - - ######################################################### - # wildcard match route is in allowed_routes - # e.g calling /anthropic/v1/messages is allowed if allowed_routes has /anthropic/* - ######################################################### - if any( - RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route) - for allowed_route in allowed_routes - if RouteChecks.is_wildcard_pattern(pattern=allowed_route) - ): - return True - - ######################################################### - # pattern match route is in allowed_routes - # pattern: "/threads/{thread_id}" - # route: "/threads/thread_49EIN5QF32s4mH20M7GFKdlZ" - # returns: True - ######################################################### - if any( # Check pattern match - RouteChecks._route_matches_pattern(route=route, pattern=allowed_route) for allowed_route in allowed_routes - ): - return True - - return False + return routes.match_route(route, tuple(allowed_routes)) @staticmethod def get_request_method(request: Request | None) -> str | None: @@ -755,13 +318,7 @@ class RouteChecks: @staticmethod def is_self_scoped_credential_route(route: str, request: Request | None) -> bool: - method: Final = RouteChecks.get_request_method(request) - if method is None: - return False - return any( - method == expected_method and RouteChecks.check_route_access(route=route, allowed_routes=(pattern,)) - for expected_method, pattern in _SELF_SCOPED_CREDENTIAL_ROUTES - ) + return route_policy_adapter.classify(route, "SelfCredential", RouteChecks.get_request_method(request)) @staticmethod def is_auth_enforced_pass_through_route(route: str, method: str | None = None) -> bool: @@ -793,48 +350,13 @@ class RouteChecks: @staticmethod def _route_matches_denied_route(route: str, denied_route: str) -> bool: - """A `/` entry denies every route, since every route sits under the root.""" - normalized_denied_route: Final = denied_route.rstrip("/") or "/" - return ( - normalized_denied_route == "/" - or RouteChecks._route_matches_allowed_route(route=route, allowed_route=normalized_denied_route) - or RouteChecks.route_matches_wildcard_pattern(route=route, pattern=denied_route) - ) + return routes.match_route(route, (denied_route,), "Denied") @staticmethod def matching_denied_passthrough_route( route: str, metadata_sources: Iterable[Mapping[str, object] | None] ) -> str | None: - """ - First ``denied_passthrough_routes`` entry across ``metadata_sources`` that matches ``route``. - Unlike the allowlist (key list, else team list), every source's deny list applies. - """ - denied_routes: Final = tuple( - itertools.chain.from_iterable( - cast( # cast-ok: management endpoints validate this metadata key as a list of route strings on write - "list[str]", (metadata or {}).get("denied_passthrough_routes") or [] - ) - for metadata in metadata_sources - ) - ) - if not denied_routes: - return None - from litellm.proxy.pass_through_endpoints.pass_through_endpoints import ( - InitPassThroughEndpointHelpers, - ) - - forwarded_routes: Final = InitPassThroughEndpointHelpers.forwarded_routes(route) - return next( - ( - denied_route - for denied_route in denied_routes - if any( - RouteChecks._route_matches_denied_route(route=candidate, denied_route=denied_route) - for candidate in forwarded_routes - ) - ), - None, - ) + return route_policy_adapter.denied_passthrough(route, metadata_sources) @staticmethod def passthrough_route_denied_exception(route: str, denied_route: str) -> HTTPException: @@ -857,16 +379,7 @@ class RouteChecks: @staticmethod def jwt_team_routes_grant_pass_through(route: str, team_allowed_routes: Collection[str]) -> bool: - """ - Explicit paths and trailing-wildcard prefixes grant auth=true pass-through. Blanket grants never do: - a named route group like ``openai_routes`` is only ever compared as a path, and an entry that names - no path segment (``*``, ``/*``) is skipped. - """ - return any( - RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route) - for allowed_route in team_allowed_routes - if allowed_route.rstrip("*").strip("/") - ) + return routes.match_route(route, tuple(team_allowed_routes), "Jwt") @staticmethod def _jwt_team_allowed_routes(valid_token: UserAPIKeyAuth) -> Collection[str]: @@ -884,46 +397,16 @@ class RouteChecks: valid_token: UserAPIKeyAuth, jwt_team_allowed_routes: Collection[str] = (), ) -> None: - """ - Require an explicit grant for auth=true pass-through: ``allowed_passthrough_routes`` on the - key or team, or an explicit JWT ``team_allowed_routes`` entry. A key or team - ``denied_passthrough_routes`` match blocks the route even when one of those grants it. - """ - RouteChecks._raise_if_passthrough_route_denied(route=route, valid_token=valid_token) - if RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token): - return - if RouteChecks.jwt_team_routes_grant_pass_through(route=route, team_allowed_routes=jwt_team_allowed_routes): - return - raise RouteChecks._auth_pass_through_denied_exception(route=route) + decision: Final = routes.passthrough_route( + routes.RouteContext(route), + route_policy_adapter.passthrough_facts(route, valid_token, jwt_team_allowed_routes, include_denied=True), + required=True, + ) + route_policy_adapter.raise_route_denial(decision, route, token=valid_token) @staticmethod def check_passthrough_route_access(route: str, user_api_key_dict: UserAPIKeyAuth) -> bool: - """ - Check if route is a passthrough route. - Supports both exact match and prefix match. - """ - metadata: Final = user_api_key_dict.metadata - team_metadata: Final = user_api_key_dict.team_metadata or {} - if metadata is None and team_metadata is None: - return False - if "allowed_passthrough_routes" not in metadata and "allowed_passthrough_routes" not in team_metadata: - return False - if ( - metadata.get("allowed_passthrough_routes") is None - and team_metadata.get("allowed_passthrough_routes") is None - ): - return False - - allowed_passthrough_routes: Final = ( - metadata.get("allowed_passthrough_routes") or team_metadata.get("allowed_passthrough_routes") or [] - ) - - # Check if route matches any allowed passthrough route (exact or prefix match) - for allowed_route in allowed_passthrough_routes: - if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route): - return True - - return False + return routes.passthrough_route(routes.RouteContext(route), route_policy_adapter.passthrough_facts(route, user_api_key_dict)).allowed @staticmethod def is_assistants_api_request(request: Request) -> bool: @@ -1004,117 +487,4 @@ class RouteChecks: request_data: dict, request: Request | None = None, ) -> None: - """ - Check access for PROXY_ADMIN_VIEW_ONLY role. - - Admin Viewer follows a read-parity-with-Proxy-Admin rule: anything Proxy - Admin can read/list/get, Admin Viewer can read/list/get. The only - exclusions are cost-incurring inference routes (Playground, /chat/ - completions, etc.) and any state-mutating request. - - Implementation: - 1. LLM/inference routes → 403 (cost-incurring). - 2. Safe HTTP method (GET/HEAD/OPTIONS) → allow by default. This is - the read-parity guarantee — every new GET endpoint added anywhere - in the codebase is automatically readable by Admin Viewer - without needing to remember to add it to an allowlist. - 3. Unsafe HTTP method (POST/PUT/PATCH/DELETE): - - Allow `/user/update` only when restricted to user_email. - - Allow `/user/password/change` (endpoint only writes the caller's own row). - - Block all explicit writes in `_ADMIN_VIEWER_BLOCKED_WRITE_ROUTES`. - - Otherwise allow only if the route is in admin_viewer_routes / - global_spend_tracking_routes (legacy explicit-allow set). - - Else 403. - """ - if RouteChecks.is_llm_api_route(route=route): - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"user not allowed to access this OpenAI routes, role= {_user_role}", - ) - - # Check if this is a write operation on management routes - if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.management_routes.value): - # For management routes, only allow read operations or specific allowed updates - if route == "/user/update": - # Check the Request params are valid for PROXY_ADMIN_VIEW_ONLY - if request_data is not None and isinstance(request_data, dict): - _params_updated: Final = request_data.keys() - for param in _params_updated: - if param != "user_email": - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route} and updating invalid param: {param}. only user_email can be updated", - ) - elif RouteChecks.check_route_access(route=route, allowed_routes=_PROXY_ADMIN_VIEW_ONLY_BLOCKED_ROUTES) or ( - route.startswith("/key/") and route.endswith(_PROXY_ADMIN_VIEW_ONLY_BLOCKED_KEY_SUFFIXES) - ): - # Block write operations for PROXY_ADMIN_VIEW_ONLY - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route}", - ) - # Allow read operations on management routes (like /user/info, /team/info, /model/info) - method: Final = request.method.upper() if request is not None else "GET" - is_safe_method: Final = method in RouteChecks._SAFE_HTTP_METHODS - - # ── Safe HTTP method: default-allow ────────────────────────────── - if is_safe_method: - return - - # ── Unsafe HTTP method: explicit checks ────────────────────────── - # Allow `/user/update` for self-service email change. - if route == "/user/update": - if request_data is not None and isinstance(request_data, dict): - for param in request_data: - if param != "user_email": - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=( - f"user not allowed to access this route, role= {_user_role}. " - f"Trying to access: {route} and updating invalid param: {param}. " - "only user_email can be updated" - ), - ) - return - - # Self-service password change; the endpoint only writes the caller's own row. - if route == "/user/password/change": - return - - # Self-service logout; the endpoint only revokes the caller's own session key. - if route == "/session/logout": - return - - if RouteChecks.is_self_scoped_credential_route(route=route, request=request): - return - - # Hard-block known write routes regardless of HTTP method (defensive - # — these are POSTs in practice, but pinning them here protects - # against future GET-shaped writes). - if RouteChecks.check_route_access( - route=route, allowed_routes=RouteChecks._ADMIN_VIEWER_BLOCKED_WRITE_ROUTES - ) or (route.startswith("/key/") and route.endswith("/regenerate")): - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route}", - ) - - # Legacy explicit-allow sets (kept for routes that are POST but - # semantically read-only, e.g. /spend/calculate). Both admin_viewer_routes - # and global_spend_tracking_routes are reads/listings. - if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.admin_viewer_routes.value): - return - if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.global_spend_tracking_routes.value): - return - - # NOTE: We intentionally do NOT fall back to allowing all - # `management_routes`. That set is a mix of reads (info/list — handled - # via the safe-method branch above) and writes (`/team/block`, - # `/team/permissions_update`, `/jwt/key/mapping/{new,update,delete}`, - # `/key/bulk_update`, `/key/{id}/reset_spend`). A blanket allow would - # let Admin Viewer POST these write endpoints — violating the - # "no writes, ever" rule. Default-deny instead. - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route}", - ) + return route_policy_adapter.check_viewer_route(route, _user_role, request_data, request) diff --git a/litellm/proxy/auth/route_policy_adapter.py b/litellm/proxy/auth/route_policy_adapter.py new file mode 100644 index 00000000000..bedff6fc3f5 --- /dev/null +++ b/litellm/proxy/auth/route_policy_adapter.py @@ -0,0 +1,239 @@ +from collections.abc import Collection, Iterable, Mapping +from dataclasses import replace +from typing import Final, Literal + +from fastapi import HTTPException, Request +from pydantic import BaseModel, Field, TypeAdapter + +from litellm._auth import routes +from litellm.proxy._types import LiteLLM_UserTable, LiteLLMRoutes, UserAPIKeyAuth + +_STRINGS: Final = TypeAdapter(tuple[str, ...]) + + +class _TokenFields(BaseModel, frozen=True): + allowed_routes: object = None + metadata: Mapping[str, object] | None = Field(default_factory=dict[str, object]) + permissions: Mapping[str, object] | None = None + + +class _ProxyFields(BaseModel, frozen=True): + general_settings: Mapping[str, object] + premium_user: bool + + +def _allowed_routes(value: object) -> tuple[str, ...] | None: + return _STRINGS.validate_python(value) if isinstance(value, list) else None + + +def route_catalog() -> routes.RouteCatalog: + from litellm.proxy.agent_endpoints.auth.managed_authorization import ( + _MANAGED_LIVE_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + _MANAGED_MCP_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + _MANAGED_MODEL_PATHS, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + _MANAGED_MODEL_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + _MANAGED_REALTIME_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + ) + from litellm.proxy.auth.route_checks import ( + _PROXY_ADMIN_VIEW_ONLY_BLOCKED_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + _SELF_SCOPED_CREDENTIAL_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + _UNBILLED_ROUTES, # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + RouteChecks, + ) + + return routes.RouteCatalog( + groups={name: tuple(member.value) for name, member in LiteLLMRoutes.__members__.items()}, + viewer_blocked=tuple(_PROXY_ADMIN_VIEW_ONLY_BLOCKED_ROUTES), + viewer_write_blocked=tuple(RouteChecks._ADMIN_VIEWER_BLOCKED_WRITE_ROUTES), # pyright: ignore[reportPrivateUsage] # read-only legacy catalog projection + self_credentials=_SELF_SCOPED_CREDENTIAL_ROUTES, + managed_models=tuple(_MANAGED_MODEL_ROUTES), + managed_paths=_MANAGED_MODEL_PATHS, + managed_realtime=tuple(_MANAGED_REALTIME_ROUTES), + managed_live=tuple(_MANAGED_LIVE_ROUTES), + managed_mcp=_MANAGED_MCP_ROUTES, + unbilled=tuple(_UNBILLED_ROUTES), + ) + + +def route_context(route: str, method: str | None = None, *, registration: bool = False) -> routes.RouteContext: + if not registration: + return routes.RouteContext(route=route, method=method, catalog=route_catalog()) + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import InitPassThroughEndpointHelpers + + registered: Final = InitPassThroughEndpointHelpers.get_registered_pass_through_route(route=route, method=method) + return routes.RouteContext( + route=route, + method=method, + catalog=route_catalog(), + registered=InitPassThroughEndpointHelpers.is_registered_pass_through_route(route), + registered_auth=registered.get("auth") is True if registered is not None else None, + configured_eu_jev=InitPassThroughEndpointHelpers.has_configured_route_ignoring_trailing_slash( + "/eu_jev/v1/systemone" + ), + ) + + +def passthrough_facts( + route: str, token: UserAPIKeyAuth, jwt_team_routes: Collection[str] = (), *, include_denied: bool = False +) -> routes.PassThroughFacts: + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import InitPassThroughEndpointHelpers + + metadata: Final = _TokenFields.model_validate(token, from_attributes=True).metadata or {} + return routes.PassThroughFacts( + key_allowed=_STRINGS.validate_python(metadata.get("allowed_passthrough_routes") or ()), + team_allowed=_STRINGS.validate_python((token.team_metadata or {}).get("allowed_passthrough_routes") or ()), + denied=( + *_STRINGS.validate_python(metadata.get("denied_passthrough_routes") or ()), + *_STRINGS.validate_python((token.team_metadata or {}).get("denied_passthrough_routes") or ()), + ) + if include_denied + else (), + forwarded=InitPassThroughEndpointHelpers.forwarded_routes(route) if include_denied else (), + jwt_team_routes=tuple(jwt_team_routes), + ) + + +def raise_route_denial( + decision: routes.RouteDecision, + route: str, + *, + token: UserAPIKeyAuth | None = None, + role: str | None = None, + user: LiteLLM_UserTable | None = None, + query_user_id: str | None = None, +) -> None: + from litellm.proxy.auth.route_checks import RouteChecks + + match decision.denial: + case None: + return + case "AdminOnly": + RouteChecks._raise_admin_only_route_exception(user_obj=user, route=route) # pyright: ignore[reportPrivateUsage] # preserve the public exception envelope + case "PassThrough": + raise RouteChecks._auth_pass_through_denied_exception(route) # pyright: ignore[reportPrivateUsage] # preserve the public exception envelope + case "DeniedPassThrough": + raise RouteChecks.passthrough_route_denied_exception(route, decision.detail or "") + case "VirtualRoute": + raise HTTPException( + 403, + f"Virtual key is not allowed to call this route. Only allowed to call routes: {_TokenFields.model_validate(token, from_attributes=True).allowed_routes if token is not None else None}. Tried to call route: {route}", + ) + case "PasswordReset": + raise HTTPException( + 403, + "This account's password must be changed before the session can be used: " + "it was either found in a known data breach or set by an admin. " + "Change it via POST /user/password/change (UI: /ui/change-password), then log in again.", + ) + case "CustomAdmin": + raise HTTPException(403, f"user not allowed to access this route. Route={route} is an admin only route") + case "UserInfo": + raise HTTPException( + 403, + f"key not allowed to access this user's info. user_id={query_user_id}, key's user_id={token.user_id if token is not None else None}", + ) + case "ViewerInference": + raise HTTPException(403, f"user not allowed to access this OpenAI routes, role= {role}") + case "ViewerWrite": + raise HTTPException(403, f"user not allowed to access this route, role= {role}. Trying to access: {route}") + case "ViewerParameter": + raise HTTPException( + 403, + f"user not allowed to access this route, role= {role}. Trying to access: {route} and updating invalid param: {decision.detail}. only user_email can be updated", + ) + + +def check_virtual_route(route: str, token: UserAPIKeyAuth, request: Request | None) -> bool: + from litellm.proxy.auth.route_checks import RouteChecks + + fields: Final = _TokenFields.model_validate(token, from_attributes=True) + facts: Final = routes.VirtualRouteFacts( + context=route_context(route, RouteChecks.get_request_method(request), registration=True), + allowed_routes=_allowed_routes(fields.allowed_routes), + passthrough=passthrough_facts(route, token), + password_reset_required=(fields.metadata or {}).get("password_reset_required") is True, + ) + raise_route_denial(routes.virtual_route(facts), route, token=token) + return True + + +def check_viewer_route(route: str, role: str, request_data: Mapping[str, object], request: Request | None) -> None: + from litellm.proxy.auth.route_checks import RouteChecks + + context: Final = route_context(route, RouteChecks.get_request_method(request), registration=True) + facts: Final = routes.ViewerFacts( + replace(context, method="") if request is not None and context.method is None else context, tuple(request_data) + ) + raise_route_denial(routes.viewer_route(facts), route, role=role) + + +def check_non_admin_route( + user: LiteLLM_UserTable | None, + role: str | None, + route: str, + request: Request, + token: UserAPIKeyAuth, + request_data: Mapping[str, object], +) -> None: + from litellm.proxy import proxy_server + from litellm.proxy.auth.route_checks import RouteChecks + + proxy: Final = _ProxyFields.model_validate(vars(proxy_server)) + fields: Final = _TokenFields.model_validate(token, from_attributes=True) + singular: Final = request_data.get("organization_id") + plural: Final = request_data.get("organizations") + organization_ids: Final = ( + *((singular,) if isinstance(singular, str) else ()), + *(_STRINGS.validate_python(plural) if isinstance(plural, list) else ()), + ) + context: Final = route_context(route, RouteChecks.get_request_method(request), registration=True) + facts: Final = routes.NonAdminFacts( + viewer=routes.ViewerFacts( + replace(context, method="") if context.method is None else context, tuple(request_data) + ), + role=role, + custom_admin_routes=_STRINGS.validate_python(proxy.general_settings.get("admin_only_routes") or ()), + premium=proxy.premium_user is True, + query_user_id=request.query_params.get("user_id") if route == "/user/info" else None, + token_user_id=token.user_id, + permissions=tuple(fields.permissions or ()), + organization_ids=organization_ids, + admin_organization_ids=tuple( + membership.organization_id + for membership in (user.organization_memberships or ()) + if membership.user_role == "org_admin" + ) + if user is not None + else (), + team_service_account=bool(token.is_team_service_account), + allowed_routes=_allowed_routes(fields.allowed_routes), + passthrough=passthrough_facts(route, token, RouteChecks._jwt_team_allowed_routes(token), include_denied=True), # pyright: ignore[reportPrivateUsage] # project legacy JWT team route metadata + ) + raise_route_denial( + routes.non_admin_route(facts), route, token=token, role=role, user=user, query_user_id=facts.query_user_id + ) + + +def classify( + route: str, + kind: Literal["Llm", "Unbilled", "Discovery", "SelfCredential", "Azure", "Managed"], + method: str | None = None, +) -> bool: + return routes.classify_route(route_context(route, method, registration=kind == "Llm"), kind) + + +def denied_passthrough(route: str, metadata_sources: Iterable[Mapping[str, object] | None]) -> str | None: + from itertools import chain + + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import InitPassThroughEndpointHelpers + + facts: Final = routes.PassThroughFacts( + denied=tuple( + chain.from_iterable( + _STRINGS.validate_python((source or {}).get("denied_passthrough_routes") or ()) + for source in metadata_sources + ) + ), + forwarded=InitPassThroughEndpointHelpers.forwarded_routes(route), + ) + return routes.denied_passthrough_route(route, facts).detail diff --git a/litellm/rust_bridge/_native.pyi b/litellm/rust_bridge/_native.pyi index 733bf9ba81d..4cc7bf4f761 100644 --- a/litellm/rust_bridge/_native.pyi +++ b/litellm/rust_bridge/_native.pyi @@ -38,6 +38,12 @@ def request_auth_select_api_key(keys: object) -> dict[str, str] | None: ... def request_auth_select_websocket_api_key(keys: object) -> dict[str, str]: ... def request_auth_scheme_credential(value: str) -> str | None: ... def request_auth_litellm_header_token(value: str) -> str: ... +def request_auth_route_access(request: object) -> object: ... +def request_auth_org_route(facts: object) -> object: ... +def request_auth_org_admin(memberships: object, organizations: tuple[str, ...]) -> bool: ... +def request_auth_model_access(request: object) -> object: ... +def request_auth_model_groups(facts: object) -> object: ... +def request_auth_fallback_access(facts: object) -> object: ... @final class NativeClickHouseSpendConfig: diff --git a/tests/unit/_auth/support/model_reference.py b/tests/unit/_auth/support/model_reference.py new file mode 100644 index 00000000000..25d6e2e883d --- /dev/null +++ b/tests/unit/_auth/support/model_reference.py @@ -0,0 +1,85 @@ +import re +from dataclasses import replace +from typing import Final + +from litellm._auth.model_access import ModelAccessDecision, ModelAccessFacts + + +def _pattern(model: str, pattern: str) -> bool: + return "*" in pattern and re.match("^" + re.escape(pattern).replace(r"\*", ".*") + "$", model) is not None + + +def helper(model: str, facts: ModelAccessFacts, *, team_aliases: bool = True) -> bool: + ordinary: Final = tuple(grant for grant in facts.grants if grant != "all-team-models") + expanded: Final = tuple(dict.fromkeys((*ordinary, *facts.registry.names))) + grants: Final = ( + (expanded or facts.grants) + if "all-team-models" in facts.grants and facts.team_id is not None and facts.registry.present + else facts.grants + ) + record: Final = facts.registry.records.get(model) + groups: Final = record.access_groups if record is not None else () + if facts.registry.present and any(grant in groups for grant in grants): + return True + filtered: Final = tuple(grant for grant in grants if grant not in groups) + if team_aliases and model in facts.aliases.team: + return True + if any(_pattern(model, grant) for grant in filtered): + return True + provider: Final = record.provider if record is not None else None + if ( + provider is not None + and (provider.stripped_model != model or "/" not in model) + and any(_pattern(f"{provider.provider}/{provider.stripped_model}", grant) for grant in filtered) + ): + return True + return not grants or "*" in filtered or "all-proxy-models" in filtered or model in filtered + + +def model_access(facts: ModelAccessFacts) -> ModelAccessDecision: + if facts.fallback_depth >= facts.max_depth: + return ModelAccessDecision("Depth") + if facts.is_list: + for model in facts.requested: + decision: Final = model_access( + replace(facts, requested=(model,), fallback_depth=facts.fallback_depth + 1, is_list=False) + ) + if decision.kind != "Allow": + return replace(decision, model=model) if decision.kind == "Depth" else decision + return ModelAccessDecision("Allow") + for model in facts.requested: + after_team: Final = facts.aliases.team.get(model, model) + after_key: Final = facts.aliases.key.get(after_team, after_team) + after_global: Final = facts.aliases.global_.get(after_key, after_key) + dispatched: Final = facts.aliases.key.get(after_global, after_global) + key_applied: Final = after_key != after_team or dispatched != after_global + alias: Final = ( + facts.aliases.global_.get(model) if model in facts.aliases.global_ else facts.registry.aliases.get(model) + ) + parent: Final = facts.registry.compaction_parents.get(model) + potential: Final = ( + (dispatched,) + if key_applied + else (model, *((parent,) if parent is not None else ()), *((alias,) if alias else ())) + ) + if any(helper(candidate, facts) for candidate in potential): + continue + record: Final = facts.registry.records.get(model) + public: Final = ( + record.deployment_public_name if record is not None and record.deployment_team == facts.team_id else None + ) + owning: Final = ( + ( + *((public,) if public else ()), + *(alias for alias, target in facts.aliases.team.items() if target == model), + ) + if not key_applied + and facts.registry.present + and facts.team_id is not None + and model.startswith(f"model_name_{facts.team_id}_") + else () + ) + if any(helper(candidate, facts, team_aliases=False) for candidate in owning): + continue + return ModelAccessDecision("Deny", model, facts.grants, facts.object_type) + return ModelAccessDecision("Allow") diff --git a/tests/unit/_auth/support/route_reference.py b/tests/unit/_auth/support/route_reference.py new file mode 100644 index 00000000000..57366d543b2 --- /dev/null +++ b/tests/unit/_auth/support/route_reference.py @@ -0,0 +1,1120 @@ +import itertools +import re +from collections.abc import Collection, Iterable, Mapping +from typing import Final, cast + +from fastapi import HTTPException, Request, status + +from litellm._logging import verbose_proxy_logger +from litellm.proxy._types import ( + MODEL_LIST_ROUTES, + UI_TEAM_ID, + CommonProxyErrors, + KeyManagementRoutes, + LiteLLM_UserTable, + LiteLLMRoutes, + LitellmUserRoles, + ProxyErrorTypes, + ProxyException, + UserAPIKeyAuth, +) + +from litellm.proxy.auth.auth_checks_organization import ( # noqa: F401 # legacy module exports + _user_is_org_admin, # pyright: ignore[reportPrivateUsage,reportUnusedImport] # backwards-compatible package export + user_is_org_admin, +) + +# Management write routes denied to PROXY_ADMIN_VIEW_ONLY. Adding a new write +# endpoint to a management router REQUIRES adding it here too — the surrounding +# check falls through to "allow" if the route is not matched, which previously +# let view-only admins call /team/block, /team/unblock, /key/bulk_update, etc. +_PROXY_ADMIN_VIEW_ONLY_BLOCKED_ROUTES: Final = frozenset( + [ + # user + "/user/new", + "/management/v1/users/bulk", + "/user/delete", + "/management/v1/users/bulk_delete", + "/user/bulk_update", + # team + "/team/new", + "/management/v1/teams/{team_id}/members/bulk_delete", + "/management/v1/teams/{team_id}/members/bulk_update", + "/team/update", + "/team/delete", + "/team/block", + "/team/unblock", + "/team/permissions_update", + "/team/permissions_bulk_update", + # model + "/model/new", + "/model/update", + "/model/delete", + # JWT key mapping + "/jwt/key/mapping/new", + "/jwt/key/mapping/update", + "/jwt/key/mapping/delete", + # key management — keep in sync with KeyManagementRoutes write entries + KeyManagementRoutes.KEY_GENERATE.value, + KeyManagementRoutes.KEY_UPDATE.value, + KeyManagementRoutes.KEY_DELETE.value, + KeyManagementRoutes.KEY_REGENERATE.value, + KeyManagementRoutes.KEY_GENERATE_SERVICE_ACCOUNT.value, + KeyManagementRoutes.KEY_BLOCK.value, + KeyManagementRoutes.KEY_UNBLOCK.value, + KeyManagementRoutes.KEY_BULK_UPDATE.value, + KeyManagementRoutes.TEAM_KEY_BULK_UPDATE.value, + ] +) + +# Suffixes for `/key/{key_id}/...` path-parameterized write routes that the +# enum templates with `{key_id}`. The blocklist above can't match templated +# paths directly because the request route carries the resolved key id. +_PROXY_ADMIN_VIEW_ONLY_BLOCKED_KEY_SUFFIXES: Final = ("/regenerate", "/reset_spend") + +_LLM_API_ROUTE_GROUPS: Final = frozenset(("llm_api_routes", "llm_api_routes_without_mcp")) +_EU_JEV_DECISION_ROUTE: Final = "/eu_jev/v1/systemone" +_AUTH_ENFORCED_PASS_THROUGH_ROUTE_GROUPS: Final = frozenset(("openai_routes", *_LLM_API_ROUTE_GROUPS)) + +# Writes that only touch the caller's own credential row (BYOK connections and +# per-user MCP credentials). Method-scoped because the generic credential CRUD +# handlers share these paths: the route check cannot admit PATCH/DELETE on a +# name like "user_connections" without also opening the admin CRUD handlers. +_SELF_SCOPED_CREDENTIAL_ROUTES: Final = ( + ("GET", "/credentials/user_connections"), + ("POST", "/credentials/{credential_name:path}/user_connection/start"), + ("POST", "/credentials/{credential_name:path}/user_connection/poll"), + ("DELETE", "/credentials/{credential_name:path}/user_connection"), + ("POST", "/v1/mcp/server/oauth/{server_id}/register"), + ("POST", "/v1/mcp/server/{server_id}/oauth-user-credential"), + ("DELETE", "/v1/mcp/server/{server_id}/oauth-user-credential"), + ("POST", "/v1/mcp/server/{server_id}/user-credential"), + ("DELETE", "/v1/mcp/server/{server_id}/user-credential"), + ("POST", "/v1/mcp/server/{server_id}/user-env-vars"), + ("DELETE", "/v1/mcp/server/{server_id}/user-env-vars"), +) + + +_UNBILLED_ROUTES: Final[frozenset[str]] = frozenset( + { + *MODEL_LIST_ROUTES, + "/utils/token_counter", + "/utils/transform_request", + "/responses/input_tokens", + "/v1/responses/input_tokens", + "/openai/v1/responses/input_tokens", + } +) +_TOKEN_COUNTING_SEGMENTS: Final[frozenset[str]] = frozenset({"count_tokens", "count-tokens"}) +_TOKEN_COUNTING_ACTION: Final = "countTokens" + + +class RouteChecks: + @staticmethod + def check_route_enabled(route: str) -> None: + try: + from litellm_enterprise.proxy.auth.route_checks import EnterpriseRouteChecks + + EnterpriseRouteChecks.should_call_route(route=route) + except HTTPException as e: + raise e + except Exception: + pass + + @staticmethod + def should_call_route( + route: str, + valid_token: UserAPIKeyAuth, + request: Request | None = None, + ): + """ + Check if management route is disabled and raise exception + """ + RouteChecks.check_route_enabled(route) + # Check if Virtual Key is allowed to call the route - Applies to all Roles + RouteChecks.is_virtual_key_allowed_to_call_route(route=route, valid_token=valid_token, request=request) + return True + + @staticmethod + def is_virtual_key_allowed_to_call_route( + route: str, + valid_token: UserAPIKeyAuth, + request: Request | None = None, + ) -> bool: + """ + Raises Exception if Virtual Key is not allowed to call the route + """ + + # Only check if valid_token.allowed_routes is set and is a list with at least one item + if valid_token.allowed_routes is None: + return True + if not isinstance(valid_token.allowed_routes, list): + return True + if len(valid_token.allowed_routes) == 0: + return True + + denied_auth_enforced_pass_through_route = False + + # explicit check for allowed routes (exact match or prefix match) + for allowed_route in valid_token.allowed_routes: + if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route): + return True + + ## check if 'allowed_route' is a field name in LiteLLMRoutes + if any(allowed_route in LiteLLMRoutes._member_names_ for allowed_route in valid_token.allowed_routes): + for allowed_route in valid_token.allowed_routes: + if allowed_route in LiteLLMRoutes._member_names_: + if RouteChecks.check_route_access( + route=route, + allowed_routes=LiteLLMRoutes[allowed_route].value, + ): + if ( + allowed_route in _AUTH_ENFORCED_PASS_THROUGH_ROUTE_GROUPS + and RouteChecks.is_auth_enforced_pass_through_route( + route=route, + method=RouteChecks.get_request_method(request=request), + ) + ): + if RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token): + return True + denied_auth_enforced_pass_through_route = True + else: + return True + + ################################################ + # For llm_api_routes, also check registered pass-through endpoints + ################################################ + if allowed_route in _LLM_API_ROUTE_GROUPS: + if route == "/auto_router/session" and RouteChecks.get_request_method(request) == "GET": + return True + + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import ( + InitPassThroughEndpointHelpers, + ) + + if InitPassThroughEndpointHelpers.is_registered_pass_through_route(route=route): + if RouteChecks.is_auth_enforced_pass_through_route( + route=route, + method=RouteChecks.get_request_method(request=request), + ): + if RouteChecks.check_passthrough_route_access( + route=route, user_api_key_dict=valid_token + ): + return True + denied_auth_enforced_pass_through_route = True + else: + return True + + # Method-aware carve-out: allow GET on the two + # read-only MCP-server discovery endpoints + # (`/v1/mcp/server` and `/v1/mcp/server/{server_id}`) + # so virtual keys with allowed_routes=["llm_api_routes"] + # can list/inspect MCP servers. The GET handlers in + # mcp_management_endpoints.py sanitize the response + # for restricted virtual keys (stripping url, + # headers, env, credentials). POST/PUT/DELETE on + # these paths are admin-only management writes and + # are intentionally not covered. + if allowed_route == "llm_api_routes" and RouteChecks._is_get_mcp_server_discovery_route( + route=route, request=request + ): + return True + + # Agent registry CRUD moved from llm_api_routes into + # management_routes so DISABLE_LLM_API_ENDPOINTS stops + # blocking it. Keys configured with + # allowed_routes=["llm_api_routes"] before that split + # could reach these paths, so keep them reachable here; + # the handlers in agent_endpoints/endpoints.py still + # enforce proxy-admin on writes and scope reads by role. + if allowed_route == "llm_api_routes" and RouteChecks.check_route_access( + route=route, + allowed_routes=LiteLLMRoutes.agent_management_routes.value, + ): + return True + + # check if wildcard pattern is allowed + for allowed_route in valid_token.allowed_routes: + if RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route): + return True + + if denied_auth_enforced_pass_through_route: + raise RouteChecks._auth_pass_through_denied_exception(route=route) + + if valid_token.metadata.get("password_reset_required") is True: + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=( + "This account's password must be changed before the session can be used: " + "it was either found in a known data breach or set by an admin. " + "Change it via POST /user/password/change (UI: /ui/change-password), then log in again." + ), + ) + + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"Virtual key is not allowed to call this route. Only allowed to call routes: {valid_token.allowed_routes}. Tried to call route: {route}", + ) + + @staticmethod + def _mask_user_id(user_id: str) -> str: + """ + Mask user_id to prevent leaking sensitive information in error messages + + Args: + user_id (str): The user_id to mask + + Returns: + str: Masked user_id showing only first 2 and last 2 characters + """ + from litellm.litellm_core_utils.sensitive_data_masker import SensitiveDataMasker + + if not user_id or len(user_id) <= 4: + return "***" + + # Use SensitiveDataMasker with custom configuration for user_id + masker: Final = SensitiveDataMasker(visible_prefix=6, visible_suffix=2, mask_char="*") + + return masker.mask_value(user_id) + + @staticmethod + def _raise_admin_only_route_exception( + user_obj: LiteLLM_UserTable | None, + route: str, + ) -> None: + """ + Raise exception for routes that require proxy admin access + + Args: + user_obj (Optional[LiteLLM_UserTable]): The user object + route (str): The route being accessed + + Raises: + ProxyException: 401 with user role and masked user_id information + """ + user_role = "unknown" + user_id = "unknown" + if user_obj is not None: + user_role = user_obj.user_role or "unknown" + user_id = user_obj.user_id or "unknown" + + masked_user_id: Final = RouteChecks._mask_user_id(user_id) + raise ProxyException( + message=( + "Authentication Error, Only proxy admin can be used to generate, delete, update info for new " + f"keys/users/teams. Route={route}. Your role={user_role}. Your user_id={masked_user_id}" + ), + type=ProxyErrorTypes.auth_error, + param=None, + code=status.HTTP_401_UNAUTHORIZED, + ) + + @staticmethod + def non_proxy_admin_allowed_routes_check( + user_obj: LiteLLM_UserTable | None, + _user_role: LitellmUserRoles | None, + route: str, + request: Request, + valid_token: UserAPIKeyAuth, + request_data: dict, + ): + """ + Checks if Non Proxy Admin User is allowed to access the route + """ + + # Check user has defined custom admin routes + RouteChecks.custom_admin_only_route_check( + route=route, + ) + + if RouteChecks.is_auth_enforced_pass_through_route( + route=route, + method=RouteChecks.get_request_method(request=request), + ): + RouteChecks._require_auth_pass_through_access( + route=route, + valid_token=valid_token, + jwt_team_allowed_routes=RouteChecks._jwt_team_allowed_routes(valid_token=valid_token), + ) + elif RouteChecks.is_llm_api_route(route=route): + pass + elif RouteChecks.is_info_route(route=route): + # check if user allowed to call an info route + if route == "/key/info": + # handled by function itself + pass + elif route == "/user/info": + # check if user can access this route + query_params: Final = request.query_params + user_id: Final = query_params.get("user_id") + verbose_proxy_logger.debug("user_id: %s & valid_token.user_id: %s", user_id, valid_token.user_id) + if ( + user_id + and user_id != valid_token.user_id + and _user_role != LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value + ): + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"key not allowed to access this user's info. user_id={user_id}, key's user_id={valid_token.user_id}", + ) + elif route == "/v2/user/info": + # handled by the endpoint itself (full RBAC in handler) + pass + elif route == "/model/info": + # /model/info just shows models user has access to + pass + elif route == "/team/info": + pass # handled by function itself + elif ( + route in LiteLLMRoutes.global_spend_tracking_routes.value + and getattr(valid_token, "permissions", None) is not None + and "get_spend_routes" in getattr(valid_token, "permissions", []) + ): + pass + elif route == "/lens" or route.startswith("/lens/"): + pass # Lens authorizes the delegated role, including its POST-based read endpoints. + elif _user_role == LitellmUserRoles.PROXY_ADMIN_VIEW_ONLY.value: + RouteChecks._check_proxy_admin_viewer_access( + route=route, + _user_role=_user_role, + request_data=request_data, + request=request, + ) + elif ( + _user_role == LitellmUserRoles.INTERNAL_USER.value + and ( + RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.internal_user_routes.value) + or RouteChecks.is_self_scoped_credential_route(route=route, request=request) + ) + or user_is_org_admin(request_data=request_data, user_object=user_obj) + and RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.org_admin_allowed_routes.value) + or _user_role == LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value + and RouteChecks.check_route_access( + route=route, + allowed_routes=LiteLLMRoutes.internal_user_view_only_routes.value, + ) + or RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.self_managed_routes.value) + ): + pass + elif route.startswith("/v1/mcp/") or route.startswith("/mcp-rest/"): + pass # authN/authZ handled by api itself + elif RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token) or ( + valid_token.is_team_service_account + and RouteChecks.check_route_access( + route=route, allowed_routes=LiteLLMRoutes.team_service_account_key_routes.value + ) + ): + pass + elif valid_token.allowed_routes is not None: + # check if route is in allowed_routes (exact match or prefix match) + route_allowed = False + for allowed_route in valid_token.allowed_routes: + if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route): + route_allowed = True + break + + if RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route): + route_allowed = True + break + + if not route_allowed: + RouteChecks._raise_admin_only_route_exception(user_obj=user_obj, route=route) + else: + RouteChecks._raise_admin_only_route_exception(user_obj=user_obj, route=route) + + @staticmethod + def custom_admin_only_route_check(route: str): + from litellm.proxy.proxy_server import general_settings, premium_user + + if "admin_only_routes" in general_settings: + if premium_user is not True: + verbose_proxy_logger.error( + "Trying to use 'admin_only_routes' this is an Enterprise only feature. %s", + CommonProxyErrors.not_premium_user.value, + ) + return + if route in general_settings["admin_only_routes"]: + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"user not allowed to access this route. Route={route} is an admin only route", + ) + + @staticmethod + def is_unbilled_route(route: str) -> bool: + resource, _, action = route.rsplit("/", 1)[-1].partition(":") + return route in _UNBILLED_ROUTES or resource in _TOKEN_COUNTING_SEGMENTS or action == _TOKEN_COUNTING_ACTION + + @staticmethod + def is_llm_api_route(route: str) -> bool: + """ + Helper to checks if provided route is an OpenAI route + + + Returns: + - True: if route is an OpenAI route + - False: if route is not an OpenAI route + """ + # Ensure route is a string before performing checks + if not isinstance(route, str): + return False + + if route in LiteLLMRoutes.openai_routes.value: + return True + + if route in LiteLLMRoutes.anthropic_routes.value: + return True + + if route in LiteLLMRoutes.google_routes.value: + return True + + if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.mcp_inference_routes.value): + return True + + if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.agent_inference_routes.value): + return True + + if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.litellm_native_routes.value): + return True + + # fuzzy match routes like "/v1/threads/thread_49EIN5QF32s4mH20M7GFKdlZ" + # Check for routes with placeholders or wildcard patterns + for openai_route in LiteLLMRoutes.openai_routes.value: + # Replace placeholders with regex pattern + # placeholders are written as "/threads/{thread_id}" + if "{" in openai_route: + if RouteChecks._route_matches_pattern(route=route, pattern=openai_route): + return True + # Check for wildcard patterns like "/containers/*" + if RouteChecks.is_wildcard_pattern(pattern=openai_route): + if RouteChecks.route_matches_wildcard_pattern(route=route, pattern=openai_route): + return True + + # Check for Google routes with placeholders like "/v1beta/models/{model_name}:generateContent" + for google_route in LiteLLMRoutes.google_routes.value: + if "{" in google_route: + if RouteChecks._route_matches_pattern(route=route, pattern=google_route): + return True + + # Check for Anthropic routes with placeholders + for anthropic_route in LiteLLMRoutes.anthropic_routes.value: + if "{" in anthropic_route: + if RouteChecks._route_matches_pattern(route=route, pattern=anthropic_route): + return True + + if RouteChecks._is_azure_openai_route(route=route): + return True + + for _llm_passthrough_route in LiteLLMRoutes.mapped_pass_through_routes.value: + if route == _llm_passthrough_route or route.startswith(_llm_passthrough_route + "/"): + return True + return RouteChecks.is_builtin_eu_jev_decision_route(route=route) + + @staticmethod + def is_builtin_eu_jev_decision_route(route: str) -> bool: + if route.rstrip("/") != _EU_JEV_DECISION_ROUTE: + return False + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import ( # noqa: PLC0415 # pass_through_endpoints imports the auth stack + InitPassThroughEndpointHelpers, + ) + + return not InitPassThroughEndpointHelpers.has_configured_route_ignoring_trailing_slash( + route=_EU_JEV_DECISION_ROUTE + ) + + @staticmethod + def _is_get_mcp_server_discovery_route(route: str, request: Request | None) -> bool: + """ + Returns True if `request` is a GET against one of the two read-only + MCP-server discovery paths: + + - GET `/v1/mcp/server` (list) + - GET `/v1/mcp/server/{server_id}` (single server, single segment) + + Multi-segment paths (`/v1/mcp/server/{id}/approve`, etc.) and any + non-GET method return False, so admin-only management writes on the + same path prefix are not reachable through this carve-out. + """ + if request is None or request.method.upper() != "GET": + return False + if route == "/v1/mcp/server": + return True + prefix: Final = "/v1/mcp/server/" + if not route.startswith(prefix): + return False + remainder: Final = route[len(prefix) :] + return bool(remainder) and "/" not in remainder + + @staticmethod + def is_management_route(route: str) -> bool: + """ + Check if route is a management route + """ + return RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.management_routes.value) + + @staticmethod + def is_info_route(route: str) -> bool: + """ + Check if route is an info route + """ + return route in LiteLLMRoutes.info_routes.value + + @staticmethod + def is_dashboard_session_info_route(route: str, team_id: str | None) -> bool: + """ + Check if an Admin UI session key is calling an info route the dashboard polls in the background + """ + return team_id == UI_TEAM_ID and RouteChecks.is_info_route(route) + + @staticmethod + def _is_azure_openai_route(route: str) -> bool: + """ + Check if route is a route from AzureOpenAI SDK client + + eg. + route='/openai/deployments/vertex_ai/gemini-1.5-flash/chat/completions' + """ + # Ensure route is a string before attempting regex matching + if not isinstance(route, str): + return False + # Add support for deployment and engine model paths + deployment_pattern: Final = r"^/openai/deployments/[^/]+/[^/]+/chat/completions$" + engine_pattern: Final = r"^/engines/[^/]+/chat/completions$" + + if re.match(deployment_pattern, route) or re.match(engine_pattern, route): + return True + return False + + @staticmethod + def _route_matches_pattern(route: str, pattern: str) -> bool: + """ + Check if route matches the pattern placed in proxy/_types.py + + Example: + - pattern: "/threads/{thread_id}" + - route: "/threads/thread_49EIN5QF32s4mH20M7GFKdlZ" + - returns: True + + + - pattern: "/key/{token_id}/regenerate" + - route: "/key/regenerate/82akk800000000jjsk" + - returns: False, pattern is "/key/{token_id}/regenerate" + """ + # Ensure route is a string before attempting regex matching + if not isinstance(route, str): + return False + + def _placeholder_to_regex(match: re.Match) -> str: + placeholder: Final = match.group(0).strip("{}") + if not placeholder.endswith(":path"): + return r"[^/]+" + # A ":path" placeholder takes whatever the router's own path + # converter takes, slashes and colons alike, so an id spelled with + # either (or both) still matches the template it was mounted under. + # + # Unless the template puts a ":" literal of its own after the + # placeholder: the Google routes end in ":generateContent" and + # friends, and there the value has to stop before that suffix + # rather than swallow it and match a different verb. + # + # "[\s\S]" rather than ".", because "." stops at a newline and the + # path converter does not: a %0A anywhere in the value would leave + # the route unmatched here while still reaching the handler, which + # turns this gate into a bypass for the lists built on it. + return r"[^:]+" if ":" in match.string[match.end() :] else r"[\s\S]+" + + pattern = re.sub(r"\{[^}]+\}", _placeholder_to_regex, pattern) + # Anchor the pattern to match the entire string + pattern = f"^{pattern}$" + if re.match(pattern, route): + return True + return False + + @staticmethod + def is_wildcard_pattern(pattern: str) -> bool: + """ + Check if pattern is a wildcard pattern + """ + return pattern.endswith("*") + + _is_wildcard_pattern = is_wildcard_pattern + + @staticmethod + def route_matches_wildcard_pattern(route: str, pattern: str) -> bool: + """ + Check if route matches the wildcard pattern + + eg. + + pattern: "/scim/v2/*" + route: "/scim/v2/Users" + - returns: True + + pattern: "/scim/v2/*" + route: "/chat/completions" + - returns: False + + + pattern: "/scim/v2/*" + route: "/scim/v2/Users/123" + - returns: True + + """ + if pattern.endswith("*"): + # Get the prefix (everything before the wildcard) + prefix: Final = pattern[:-1] + return route.startswith(prefix) + else: + # If there's no wildcard, the pattern and route should match exactly + return route == pattern + + @staticmethod + def _route_matches_allowed_route(route: str, allowed_route: str) -> bool: + """ + Check if route matches the allowed_route pattern. + Supports both exact match and prefix match. + + Examples: + - allowed_route="/fake-openai-proxy-6", route="/fake-openai-proxy-6" -> True (exact match) + - allowed_route="/fake-openai-proxy-6", route="/fake-openai-proxy-6/v1/chat/completions" -> True (prefix match) + - allowed_route="/fake-openai-proxy-6", route="/fake-openai-proxy-600" -> False (not a valid prefix) + + Args: + route: The actual route being accessed + allowed_route: The allowed route pattern + + Returns: + bool: True if route matches (exact or prefix), False otherwise + """ + # Exact match + if route == allowed_route: + return True + # Prefix match - ensure we add "/" to prevent false matches like /fake-openai-proxy-600 + if route.startswith(allowed_route + "/"): + return True + return False + + @staticmethod + def check_route_access(route: str, allowed_routes: Collection[str]) -> bool: + """ + Check if a route has access by checking both exact matches and patterns + + Args: + route (str): The route to check + allowed_routes (Sequence): Allowed routes/patterns + + Returns: + bool: True if route is allowed, False otherwise + """ + ######################################################### + # exact match route is in allowed_routes + ######################################################### + if route in allowed_routes: + return True + + ######################################################### + # wildcard match route is in allowed_routes + # e.g calling /anthropic/v1/messages is allowed if allowed_routes has /anthropic/* + ######################################################### + if any( + RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route) + for allowed_route in allowed_routes + if RouteChecks.is_wildcard_pattern(pattern=allowed_route) + ): + return True + + ######################################################### + # pattern match route is in allowed_routes + # pattern: "/threads/{thread_id}" + # route: "/threads/thread_49EIN5QF32s4mH20M7GFKdlZ" + # returns: True + ######################################################### + if any( # Check pattern match + RouteChecks._route_matches_pattern(route=route, pattern=allowed_route) for allowed_route in allowed_routes + ): + return True + + return False + + @staticmethod + def get_request_method(request: Request | None) -> str | None: + if request is None: + return None + + try: + method: Final = cast( # cast-ok: request.method is str at runtime; tests hand a MagicMock + object, request.method + ) + except (AttributeError, KeyError): + return None + if not isinstance(method, str): + return None + + return method.upper() + + _get_request_method = get_request_method + + @staticmethod + def is_self_scoped_credential_route(route: str, request: Request | None) -> bool: + method: Final = RouteChecks.get_request_method(request) + if method is None: + return False + return any( + method == expected_method and RouteChecks.check_route_access(route=route, allowed_routes=(pattern,)) + for expected_method, pattern in _SELF_SCOPED_CREDENTIAL_ROUTES + ) + + @staticmethod + def is_auth_enforced_pass_through_route(route: str, method: str | None = None) -> bool: + """ + True for config/DB pass-through endpoints registered with auth=true. + + These routes are injected into ``openai_routes`` for spend/budget hooks but + must not inherit blanket ``openai_routes`` RBAC; access is gated by + ``allowed_passthrough_routes`` on the key or team. + """ + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import ( + InitPassThroughEndpointHelpers, + ) + + route_info: Final = InitPassThroughEndpointHelpers.get_registered_pass_through_route(route=route, method=method) + if route_info is None: + return False + return route_info.get("auth") is True + + @staticmethod + def _auth_pass_through_denied_exception(route: str) -> HTTPException: + return HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=( + f"Key/team not allowed to access passthrough route {route}. " + "Configure `allowed_passthrough_routes` on the team or key." + ), + ) + + @staticmethod + def _route_matches_denied_route(route: str, denied_route: str) -> bool: + """A `/` entry denies every route, since every route sits under the root.""" + normalized_denied_route: Final = denied_route.rstrip("/") or "/" + return ( + normalized_denied_route == "/" + or RouteChecks._route_matches_allowed_route(route=route, allowed_route=normalized_denied_route) + or RouteChecks.route_matches_wildcard_pattern(route=route, pattern=denied_route) + ) + + @staticmethod + def matching_denied_passthrough_route( + route: str, metadata_sources: Iterable[Mapping[str, object] | None] + ) -> str | None: + """ + First ``denied_passthrough_routes`` entry across ``metadata_sources`` that matches ``route``. + Unlike the allowlist (key list, else team list), every source's deny list applies. + """ + denied_routes: Final = tuple( + itertools.chain.from_iterable( + cast( # cast-ok: management endpoints validate this metadata key as a list of route strings on write + "list[str]", (metadata or {}).get("denied_passthrough_routes") or [] + ) + for metadata in metadata_sources + ) + ) + if not denied_routes: + return None + from litellm.proxy.pass_through_endpoints.pass_through_endpoints import ( + InitPassThroughEndpointHelpers, + ) + + forwarded_routes: Final = InitPassThroughEndpointHelpers.forwarded_routes(route) + return next( + ( + denied_route + for denied_route in denied_routes + if any( + RouteChecks._route_matches_denied_route(route=candidate, denied_route=denied_route) + for candidate in forwarded_routes + ) + ), + None, + ) + + @staticmethod + def passthrough_route_denied_exception(route: str, denied_route: str) -> HTTPException: + return HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=( + f"Key/team denied access to passthrough route {route}. " + f"Matched `{denied_route}` in `denied_passthrough_routes`." + ), + ) + + @staticmethod + def _raise_if_passthrough_route_denied(route: str, valid_token: UserAPIKeyAuth) -> None: + denied_route: Final = RouteChecks.matching_denied_passthrough_route( + route=route, + metadata_sources=(valid_token.metadata, valid_token.team_metadata), + ) + if denied_route is not None: + raise RouteChecks.passthrough_route_denied_exception(route=route, denied_route=denied_route) + + @staticmethod + def jwt_team_routes_grant_pass_through(route: str, team_allowed_routes: Collection[str]) -> bool: + """ + Explicit paths and trailing-wildcard prefixes grant auth=true pass-through. Blanket grants never do: + a named route group like ``openai_routes`` is only ever compared as a path, and an entry that names + no path segment (``*``, ``/*``) is skipped. + """ + return any( + RouteChecks.route_matches_wildcard_pattern(route=route, pattern=allowed_route) + for allowed_route in team_allowed_routes + if allowed_route.rstrip("*").strip("/") + ) + + @staticmethod + def _jwt_team_allowed_routes(valid_token: UserAPIKeyAuth) -> Collection[str]: + """``team_allowed_routes`` for team tokens built by JWT auth; JWT-mapped virtual keys stay key-scoped.""" + if valid_token.jwt_claims is None or valid_token.token is not None or valid_token.team_id is None: + return () + + from litellm.proxy.proxy_server import jwt_handler + + return jwt_handler.litellm_jwtauth.team_allowed_routes + + @staticmethod + def _require_auth_pass_through_access( + route: str, + valid_token: UserAPIKeyAuth, + jwt_team_allowed_routes: Collection[str] = (), + ) -> None: + """ + Require an explicit grant for auth=true pass-through: ``allowed_passthrough_routes`` on the + key or team, or an explicit JWT ``team_allowed_routes`` entry. A key or team + ``denied_passthrough_routes`` match blocks the route even when one of those grants it. + """ + RouteChecks._raise_if_passthrough_route_denied(route=route, valid_token=valid_token) + if RouteChecks.check_passthrough_route_access(route=route, user_api_key_dict=valid_token): + return + if RouteChecks.jwt_team_routes_grant_pass_through(route=route, team_allowed_routes=jwt_team_allowed_routes): + return + raise RouteChecks._auth_pass_through_denied_exception(route=route) + + @staticmethod + def check_passthrough_route_access(route: str, user_api_key_dict: UserAPIKeyAuth) -> bool: + """ + Check if route is a passthrough route. + Supports both exact match and prefix match. + """ + metadata: Final = user_api_key_dict.metadata + team_metadata: Final = user_api_key_dict.team_metadata or {} + if metadata is None and team_metadata is None: + return False + if "allowed_passthrough_routes" not in metadata and "allowed_passthrough_routes" not in team_metadata: + return False + if ( + metadata.get("allowed_passthrough_routes") is None + and team_metadata.get("allowed_passthrough_routes") is None + ): + return False + + allowed_passthrough_routes: Final = ( + metadata.get("allowed_passthrough_routes") or team_metadata.get("allowed_passthrough_routes") or [] + ) + + # Check if route matches any allowed passthrough route (exact or prefix match) + for allowed_route in allowed_passthrough_routes: + if RouteChecks._route_matches_allowed_route(route=route, allowed_route=allowed_route): + return True + + return False + + @staticmethod + def is_assistants_api_request(request: Request) -> bool: + """ + Returns True if `thread` or `assistant` is in the request path + + Args: + request (Request): The request object + + Returns: + bool: True if `thread` or `assistant` is in the request path, False otherwise + """ + # Inline import — auth_utils participates in a proxy import cycle. + from .auth_utils import get_request_route # noqa: PLC0415 + + route: Final = get_request_route(request) + if "thread" in route or "assistant" in route: + return True + return False + + _is_assistants_api_request = is_assistants_api_request + + @staticmethod + def is_generate_content_route(route: str) -> bool: + """ + Returns True if this is a google generateContent or streamGenerateContent route + + These routes from google allow passing key=api_key in the query params + """ + if "generateContent" in route: + return True + if "streamGenerateContent" in route: + return True + return False + + # HTTP methods that are intrinsically read-only and therefore safe to + # default-allow for PROXY_ADMIN_VIEW_ONLY. Anything else (POST/PUT/PATCH/ + # DELETE) is treated as a write attempt and goes through the explicit + # write-allowlist below. + _SAFE_HTTP_METHODS = frozenset({"GET", "HEAD", "OPTIONS"}) + + # Explicit write routes that PROXY_ADMIN_VIEW_ONLY must NEVER call. The + # role-principle is "no writes, ever" — the management_routes list is the + # authoritative source for which non-llm routes are writes; we just need + # to filter out the read endpoints (info / list) that share the prefix. + # A cleaner approach is to denylist by HTTP verb (POST/PUT/PATCH/DELETE); + # this block stays as a backstop in case a write is implemented as GET. + _ADMIN_VIEWER_BLOCKED_WRITE_ROUTES = frozenset( + [ + "/user/new", + "/management/v1/users/bulk", + "/user/delete", + "/management/v1/users/bulk_delete", + "/user/bulk_update", + "/team/new", + "/management/v1/teams/{team_id}/members/bulk_delete", + "/management/v1/teams/{team_id}/members/bulk_update", + "/team/update", + "/team/delete", + "/model/new", + "/model/update", + "/model/delete", + "/key/generate", + "/key/delete", + "/key/update", + "/key/regenerate", + "/key/service-account/generate", + "/key/block", + "/key/unblock", + "/team/key/bulk_update", + ] + ) + + @staticmethod + def _check_proxy_admin_viewer_access( + route: str, + _user_role: str, + request_data: dict, + request: Request | None = None, + ) -> None: + """ + Check access for PROXY_ADMIN_VIEW_ONLY role. + + Admin Viewer follows a read-parity-with-Proxy-Admin rule: anything Proxy + Admin can read/list/get, Admin Viewer can read/list/get. The only + exclusions are cost-incurring inference routes (Playground, /chat/ + completions, etc.) and any state-mutating request. + + Implementation: + 1. LLM/inference routes → 403 (cost-incurring). + 2. Safe HTTP method (GET/HEAD/OPTIONS) → allow by default. This is + the read-parity guarantee — every new GET endpoint added anywhere + in the codebase is automatically readable by Admin Viewer + without needing to remember to add it to an allowlist. + 3. Unsafe HTTP method (POST/PUT/PATCH/DELETE): + - Allow `/user/update` only when restricted to user_email. + - Allow `/user/password/change` (endpoint only writes the caller's own row). + - Block all explicit writes in `_ADMIN_VIEWER_BLOCKED_WRITE_ROUTES`. + - Otherwise allow only if the route is in admin_viewer_routes / + global_spend_tracking_routes (legacy explicit-allow set). + - Else 403. + """ + if RouteChecks.is_llm_api_route(route=route): + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"user not allowed to access this OpenAI routes, role= {_user_role}", + ) + + # Check if this is a write operation on management routes + if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.management_routes.value): + # For management routes, only allow read operations or specific allowed updates + if route == "/user/update": + # Check the Request params are valid for PROXY_ADMIN_VIEW_ONLY + if request_data is not None and isinstance(request_data, dict): + _params_updated: Final = request_data.keys() + for param in _params_updated: + if param != "user_email": + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route} and updating invalid param: {param}. only user_email can be updated", + ) + elif RouteChecks.check_route_access(route=route, allowed_routes=_PROXY_ADMIN_VIEW_ONLY_BLOCKED_ROUTES) or ( + route.startswith("/key/") and route.endswith(_PROXY_ADMIN_VIEW_ONLY_BLOCKED_KEY_SUFFIXES) + ): + # Block write operations for PROXY_ADMIN_VIEW_ONLY + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route}", + ) + # Allow read operations on management routes (like /user/info, /team/info, /model/info) + method: Final = request.method.upper() if request is not None else "GET" + is_safe_method: Final = method in RouteChecks._SAFE_HTTP_METHODS + + # ── Safe HTTP method: default-allow ────────────────────────────── + if is_safe_method: + return + + # ── Unsafe HTTP method: explicit checks ────────────────────────── + # Allow `/user/update` for self-service email change. + if route == "/user/update": + if request_data is not None and isinstance(request_data, dict): + for param in request_data: + if param != "user_email": + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=( + f"user not allowed to access this route, role= {_user_role}. " + f"Trying to access: {route} and updating invalid param: {param}. " + "only user_email can be updated" + ), + ) + return + + # Self-service password change; the endpoint only writes the caller's own row. + if route == "/user/password/change": + return + + # Self-service logout; the endpoint only revokes the caller's own session key. + if route == "/session/logout": + return + + if RouteChecks.is_self_scoped_credential_route(route=route, request=request): + return + + # Hard-block known write routes regardless of HTTP method (defensive + # — these are POSTs in practice, but pinning them here protects + # against future GET-shaped writes). + if RouteChecks.check_route_access( + route=route, allowed_routes=RouteChecks._ADMIN_VIEWER_BLOCKED_WRITE_ROUTES + ) or (route.startswith("/key/") and route.endswith("/regenerate")): + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route}", + ) + + # Legacy explicit-allow sets (kept for routes that are POST but + # semantically read-only, e.g. /spend/calculate). Both admin_viewer_routes + # and global_spend_tracking_routes are reads/listings. + if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.admin_viewer_routes.value): + return + if RouteChecks.check_route_access(route=route, allowed_routes=LiteLLMRoutes.global_spend_tracking_routes.value): + return + + # NOTE: We intentionally do NOT fall back to allowing all + # `management_routes`. That set is a mix of reads (info/list — handled + # via the safe-method branch above) and writes (`/team/block`, + # `/team/permissions_update`, `/jwt/key/mapping/{new,update,delete}`, + # `/key/bulk_update`, `/key/{id}/reset_spend`). A blanket allow would + # let Admin Viewer POST these write endpoints — violating the + # "no writes, ever" rule. Default-deny instead. + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"user not allowed to access this route, role= {_user_role}. Trying to access: {route}", + ) diff --git a/tests/unit/_auth/test_fallback_access.py b/tests/unit/_auth/test_fallback_access.py new file mode 100644 index 00000000000..80298084302 --- /dev/null +++ b/tests/unit/_auth/test_fallback_access.py @@ -0,0 +1,62 @@ +from dataclasses import replace +from typing import Final + +import pytest + +from litellm._auth.fallback_access import FallbackAuthorizationFacts, GroupedModelScope, fallback_authorization +from litellm._auth.model_access import ModelAccessFacts + +_ALLOW: Final = ModelAccessFacts(("model",), ("model",), object_type="key") +_DENY: Final = replace(_ALLOW, grants=("other",)) +_BASE: Final = FallbackAuthorizationFacts(GroupedModelScope(_ALLOW)) + + +@pytest.mark.parametrize( + ("facts", "kind"), + ( + pytest.param(_BASE, "Allow", id="no-extra-ceilings"), + pytest.param(replace(_BASE, refuse_agent_keys=True, agent_id=""), "Deny", id="agent-presence-not-truthiness"), + pytest.param( + replace(_BASE, key=GroupedModelScope(_DENY, ("group",))), "ReadKeyGroups", id="key-groups-before-team" + ), + pytest.param( + replace(_BASE, key=GroupedModelScope(_DENY, ("group",), ())), "Deny", id="empty-key-group-retains-denial" + ), + pytest.param( + replace(_BASE, key=GroupedModelScope(_DENY, ("group",), ("model",))), "Allow", id="key-group-fallback" + ), + pytest.param( + replace(_BASE, team=GroupedModelScope(_DENY, ("group",))), "ReadTeamGroups", id="team-group-fallback" + ), + pytest.param( + replace(_BASE, team=GroupedModelScope(_DENY)), "ReadAssignedGroups", id="team-denial-asks-owned-key-grants" + ), + pytest.param( + replace(_BASE, team=GroupedModelScope(_DENY), assigned_models=()), + "Deny", + id="empty-assigned-does-not-widen", + ), + pytest.param( + replace(_BASE, team=GroupedModelScope(_DENY), assigned_models=("model",)), + "Allow", + id="assigned-overrides-team", + ), + pytest.param( + replace(_BASE, embedded_team=_DENY, assigned_models=("model",)), + "Deny", + id="embedded-team-no-assigned-override", + ), + pytest.param(replace(_BASE, member=_DENY), "Deny", id="member-ceiling"), + pytest.param(replace(_BASE, project=_DENY), "Deny", id="project-ceiling"), + ), +) +def test_fallback_authorization_stage_order(facts: FallbackAuthorizationFacts, kind: str) -> None: + assert fallback_authorization(facts).kind == kind + + +def test_key_denial_wins_before_later_scopes() -> None: + decision: Final = fallback_authorization( + replace(_BASE, key=GroupedModelScope(_DENY), project=replace(_DENY, object_type="project")) + ) + assert decision.denial is not None + assert decision.denial.object_type == "key" diff --git a/tests/unit/_auth/test_model_access.py b/tests/unit/_auth/test_model_access.py new file mode 100644 index 00000000000..ab0ab6a551f --- /dev/null +++ b/tests/unit/_auth/test_model_access.py @@ -0,0 +1,229 @@ +from dataclasses import replace +from typing import Final + +import pytest + +from litellm._auth import model_access as native +from litellm._auth.model_access import ( + ModelAccessFacts as Facts, +) +from litellm._auth.model_access import ( + ModelAliases as Aliases, +) +from litellm._auth.model_access import ( + ModelProvider as Provider, +) +from litellm._auth.model_access import ( + ModelRecord as Record, +) +from litellm._auth.model_access import ( + ModelRegistry as Registry, +) +from tests.unit._auth.support import model_reference as reference + +_BASE: Final = Facts(("model",), object_type="key") +_CASES: Final = ( + pytest.param(_BASE, "Allow", id="empty-is-unrestricted"), + pytest.param(replace(_BASE, grants=("model",)), "Allow", id="exact-grant"), + pytest.param(replace(_BASE, grants=("other",)), "Deny", id="denied-model"), + pytest.param(replace(_BASE, grants=("*",)), "Allow", id="global-wildcard"), + pytest.param(replace(_BASE, grants=("all-proxy-models",)), "Allow", id="proxy-sentinel"), + pytest.param(replace(_BASE, grants=("mo*",)), "Allow", id="prefix-wildcard"), + pytest.param(replace(_BASE, requested=("model\n",), grants=("mo*",)), "Allow", id="python-final-newline"), + pytest.param(replace(_BASE, requested=("mod\nel",), grants=("mo*l",)), "Deny", id="embedded-newline"), + pytest.param( + replace(_BASE, grants=("p/*",), registry=Registry(records={"model": Record(provider=Provider("model", "p"))})), + "Allow", + id="inferred-provider", + ), + pytest.param( + replace( + _BASE, + requested=("p/model",), + grants=("q/*",), + registry=Registry(records={"p/model": Record(provider=Provider("model", "p"))}), + ), + "Deny", + id="different-provider", + ), + pytest.param( + replace(_BASE, grants=("other",), aliases=Aliases(team={"model": "target"})), "Allow", id="team-alias-exists" + ), + pytest.param( + replace(_BASE, grants=("model",), aliases=Aliases(key={"model": "target"})), + "Deny", + id="key-alias-replaces-source", + ), + pytest.param( + replace(_BASE, grants=("target",), aliases=Aliases(key={"model": "target"})), "Allow", id="key-target" + ), + pytest.param( + replace(_BASE, grants=("target",), aliases=Aliases(global_={"model": "target"})), "Allow", id="global-target" + ), + pytest.param( + replace( + _BASE, + grants=("target",), + aliases=Aliases( + team={"model": "middle"}, key={"middle": "third", "global": "target"}, global_={"third": "global"} + ), + ), + "Allow", + id="alias-order", + ), + pytest.param( + replace(_BASE, grants=("target",), registry=Registry(present=True, aliases={"model": "target"})), + "Allow", + id="router-alias", + ), + pytest.param( + replace( + _BASE, + grants=("target",), + registry=Registry(present=True, aliases={"model": "target"}), + aliases=Aliases(global_={"model": "wrong"}), + ), + "Deny", + id="global-over-router", + ), + pytest.param( + replace(_BASE, grants=("parent",), registry=Registry(compaction_parents={"model": "parent"})), + "Allow", + id="compaction-parent", + ), + pytest.param( + replace( + _BASE, + grants=("group",), + registry=Registry(present=True, records={"model": Record(access_groups=("group",))}), + ), + "Allow", + id="registry-group", + ), + pytest.param( + replace( + _BASE, + grants=("other-group",), + registry=Registry(present=True, records={"model": Record(access_groups=("group",))}), + ), + "Deny", + id="different-group", + ), + pytest.param( + replace(_BASE, grants=("all-team-models",), team_id="team", registry=Registry(present=True, names=("model",))), + "Allow", + id="team-sentinel-expands", + ), + pytest.param( + replace(_BASE, grants=("all-team-models",), team_id="team", registry=Registry(present=True)), + "Deny", + id="empty-registry-sentinel", + ), + pytest.param( + replace(_BASE, grants=("all-team-models",), registry=Registry(present=True, names=("model",))), + "Deny", + id="team-sentinel-no-team", + ), + pytest.param( + replace( + _BASE, + requested=("model_name_team_id",), + grants=("public",), + team_id="team", + registry=Registry( + present=True, + records={"model_name_team_id": Record(deployment_team="team", deployment_public_name="public")}, + ), + ), + "Allow", + id="owning-team-public-name", + ), + pytest.param( + replace( + _BASE, + requested=("model_name_team_id",), + grants=("public",), + team_id="team", + registry=Registry( + present=True, + records={"model_name_team_id": Record(deployment_team="other", deployment_public_name="public")}, + ), + ), + "Deny", + id="public-name-wrong-team", + ), + pytest.param( + replace( + _BASE, + requested=("model_name_team_id",), + grants=("other",), + team_id="team", + aliases=Aliases(team={"public": "model_name_team_id"}), + registry=Registry(present=True), + ), + "Deny", + id="owning-alias-not-unconditional", + ), + pytest.param( + replace(_BASE, requested=("model", "other"), grants=("model",), is_list=True), + "Deny", + id="all-list-items-required", + ), + pytest.param(replace(_BASE, requested=(), grants=("other",), is_list=True), "Allow", id="empty-list"), + pytest.param(replace(_BASE, fallback_depth=5), "Depth", id="depth"), + pytest.param(replace(_BASE, fallback_depth=4, is_list=True), "Depth", id="list-depth"), +) + + +@pytest.mark.parametrize("policy", (reference.model_access, native.model_access), ids=("reference", "native")) +@pytest.mark.parametrize(("facts", "kind"), _CASES) +def test_model_policy_case_table(policy, facts: Facts, kind: str) -> None: + decision: Final = policy(facts) + assert decision.kind == kind + assert decision == reference.model_access(facts) + + +@pytest.mark.parametrize( + ("groups", "models", "merge", "kind"), + ( + ((), None, False, "Deny"), + (("g",), None, False, "ReadGroups"), + (("g",), (), False, "Deny"), + (("g",), ("model",), False, "Allow"), + (("g",), ("model",), True, "Allow"), + (("g",), ("other",), False, "Deny"), + ), +) +def test_group_fallback_waits_for_data( + groups: tuple[str, ...], models: tuple[str, ...] | None, merge: bool, kind: str +) -> None: + assert native.grouped_model_access(replace(_BASE, grants=("no",)), groups, models, merge=merge).kind == kind + + +@pytest.mark.parametrize( + ("present", "grants", "kind"), + ( + (False, ("no-default-models",), "Allow"), + (True, ("no-default-models", "model"), "NoDefaultModels"), + (True, (), "Allow"), + (True, ("other",), "Deny"), + ), +) +def test_user_default_scope(present: bool, grants: tuple[str, ...], kind: str) -> None: + assert native.user_model_access(replace(_BASE, grants=grants), present=present).kind == kind + + +@pytest.mark.parametrize( + ("managed", "ceilings", "kind"), + ( + (None, (), "Allow"), + ((), (), "NoAgentModels"), + (("model",), ((),), "EmptyAgentCeiling"), + (("model",), (("model",), ("other",)), "Deny"), + (("model",), (("model",),), "Allow"), + ), +) +def test_agent_grants_are_intersected( + managed: tuple[str, ...] | None, ceilings: tuple[tuple[str, ...], ...], kind: str +) -> None: + assert native.agent_model_access(_BASE, managed, ceilings).kind == kind diff --git a/tests/unit/_auth/test_model_groups.py b/tests/unit/_auth/test_model_groups.py new file mode 100644 index 00000000000..572a3c8a0e6 --- /dev/null +++ b/tests/unit/_auth/test_model_groups.py @@ -0,0 +1,49 @@ +from dataclasses import replace +from typing import Final + +import pytest + +from litellm._auth.model_groups import GroupLookup, GroupResources, ResourceGroupFacts, resource_group_decision + +_BASE: Final = ResourceGroupFacts(True, True, True, ("group",), "team", "key") + + +@pytest.mark.parametrize( + ("team_ids", "key_ids", "expected"), + ( + (("team",), (), ("model",)), + ((), ("key",), ("model",)), + (("other",), (), ()), + ((), ("other",), ()), + ((), (), ()), + ), +) +def test_group_ownership_boundary( + team_ids: tuple[str, ...], key_ids: tuple[str, ...], expected: tuple[str, ...] +) -> None: + decision: Final = resource_group_decision( + replace(_BASE, loaded=(GroupLookup("Found", GroupResources(team_ids, key_ids, ("model", "model"))),)) + ) + assert (decision.kind, decision.resources) == ("Complete", expected) + + +@pytest.mark.parametrize("kind", ("Missing", "Failed")) +@pytest.mark.parametrize("check_db_only", (False, True)) +@pytest.mark.parametrize("strict_errors", (False, True)) +def test_strict_lookup_errors_stop_before_next_group(kind, check_db_only: bool, strict_errors: bool) -> None: + decision: Final = resource_group_decision( + replace( + _BASE, + group_ids=("first", "second"), + check_db_only=check_db_only, + strict_errors=strict_errors, + loaded=(GroupLookup(kind),), + ) + ) + assert (decision.kind, decision.index) == (("Raise", 0) if check_db_only or strict_errors else ("Read", 1)) + + +@pytest.mark.parametrize("field", ("subject_present", "database_present", "cache_present")) +def test_unavailable_dependency_grants_nothing(field: str) -> None: + decision: Final = resource_group_decision(replace(_BASE, **{field: False})) + assert (decision.kind, decision.resources) == ("Complete", ()) diff --git a/tests/unit/_auth/test_routes.py b/tests/unit/_auth/test_routes.py new file mode 100644 index 00000000000..aed01d185e6 --- /dev/null +++ b/tests/unit/_auth/test_routes.py @@ -0,0 +1,192 @@ +from collections.abc import Callable +from dataclasses import dataclass +from typing import Final + +import pytest +from fastapi import HTTPException, Request + +from litellm._auth import routes +from litellm.proxy._types import LiteLLMRoutes, UserAPIKeyAuth +from litellm.proxy.auth.route_checks import RouteChecks +from litellm.proxy.auth.route_policy_adapter import route_context +from tests.unit._auth.support.route_reference import RouteChecks as ReferenceRoutes + + +@dataclass(frozen=True, slots=True) +class RouteResult: + allowed: bool + status: int | None = None + detail: object = None + + +def outcome(call: Callable[[], object]) -> RouteResult: + try: + result: Final = call() + return RouteResult(result is not False) + except HTTPException as error: + return RouteResult(False, error.status_code, error.detail) + + +_ROUTES: Final = tuple( + dict.fromkeys( + ( + "/unknown", + "/chat/completions", + "/v1/mcp/server", + "/v1/mcp/server/id", + "/v1/mcp/server/id/more", + "/auto_router/session", + "/models", + "/v1/responses/id", + "/agents", + "/v1/agents/id", + "/key/id/regenerate", + "/user/update", + "/user/password/change", + "/session/logout", + "/user/info", + "/organization/new", + "/team/new", + "/openai/deployments/model/versions/chat/completions", + "/engines/model/chat/completions", + "/foo/count_tokens", + "/v1beta/models/model:countTokens", + "/unknown\n", + "/key/generate", + "/key/list", + "/session/list", + ) + ) +) + + +@pytest.mark.parametrize("route", _ROUTES) +@pytest.mark.parametrize("method", (None, "GET", "POST", "DELETE", "HEAD", "OPTIONS")) +def test_route_classifications_match_reference(route: str, method: str | None) -> None: + request: Final = Request({"type": "http", "method": method or "GET", "path": route, "headers": []}) + assert RouteChecks.is_llm_api_route(route) == ReferenceRoutes.is_llm_api_route(route) + assert RouteChecks.is_unbilled_route(route) == ReferenceRoutes.is_unbilled_route(route) + assert RouteChecks.is_self_scoped_credential_route( + route, request + ) == ReferenceRoutes.is_self_scoped_credential_route(route, request) + assert RouteChecks._is_get_mcp_server_discovery_route( + route, request + ) == ReferenceRoutes._is_get_mcp_server_discovery_route(route, request) + + +@pytest.mark.parametrize("route", _ROUTES) +@pytest.mark.parametrize( + "allowed", + ( + None, + (), + ("llm_api_routes",), + ("llm_api_routes_without_mcp",), + ("management_routes",), + ("/v1/*",), + ("/user",), + ("*",), + ("/no",), + ), +) +@pytest.mark.parametrize("method", ("GET", "POST")) +def test_virtual_route_allow_and_denial_envelope(route: str, allowed: tuple[str, ...] | None, method: str) -> None: + request: Final = Request({"type": "http", "method": method, "path": route, "headers": []}) + token: Final = UserAPIKeyAuth(allowed_routes=list(allowed) if allowed is not None else None) + assert outcome(lambda: RouteChecks.is_virtual_key_allowed_to_call_route(route, token, request)) == outcome( + lambda: ReferenceRoutes.is_virtual_key_allowed_to_call_route(route, token, request) + ) + + +@pytest.mark.parametrize("route", _ROUTES) +@pytest.mark.parametrize("method", ("GET", "POST", "PATCH", "HEAD")) +@pytest.mark.parametrize("keys", ((), ("user_email",), ("user_id", "user_email"))) +def test_viewer_role_denial_order_and_envelope(route: str, method: str, keys: tuple[str, ...]) -> None: + request: Final = Request({"type": "http", "method": method, "path": route, "headers": []}) + data: Final = {key: "value" for key in keys} + assert outcome( + lambda: RouteChecks._check_proxy_admin_viewer_access( + route=route, _user_role="proxy_admin_viewer", request_data=data, request=request + ) + ) == outcome( + lambda: ReferenceRoutes._check_proxy_admin_viewer_access( + route=route, _user_role="proxy_admin_viewer", request_data=data, request=request + ) + ) + + +@pytest.mark.parametrize("group", tuple(LiteLLMRoutes)) +def test_full_catalog_classification(group: LiteLLMRoutes) -> None: + assert tuple(RouteChecks.is_llm_api_route(route) for route in group.value) == tuple( + ReferenceRoutes.is_llm_api_route(route) for route in group.value + ) + + +@pytest.mark.parametrize( + ("route", "pattern"), + ( + ("/a/id", "/a/{id}"), + ("/a/x/y", "/a/{id:path}"), + ("/a/x/y:action", "/a/{id:path}:action"), + ("/a/x\ny", "/a/{id:path}"), + ("/a/id\n", "/a/{id}"), + ("/a/b", "/a/*"), + ("/ab", "/a"), + ("/a", ""), + ("/a", "/"), + ("/a/id:action", "/a/{id}:action"), + ("/a/id", "/a/{id:path}"), + ), +) +def test_route_pattern_modes(route: str, pattern: str) -> None: + assert RouteChecks._route_matches_pattern(route, pattern) == ReferenceRoutes._route_matches_pattern(route, pattern) + assert RouteChecks._route_matches_allowed_route(route, pattern) == ReferenceRoutes._route_matches_allowed_route( + route, pattern + ) + assert RouteChecks.route_matches_wildcard_pattern(route, pattern) == ReferenceRoutes.route_matches_wildcard_pattern( + route, pattern + ) + assert RouteChecks._route_matches_denied_route(route, pattern) == ReferenceRoutes._route_matches_denied_route( + route, pattern + ) + + +@pytest.mark.parametrize( + "route", + ( + "/agents", + "/v1/agents", + "/chat/completions", + "/v1/chat/completions", + "/v1/responses/id", + "/realtime", + "/v1/realtime", + "/v1/mcp/server/id", + "/mcp/foo", + "/user/info", + "/v1beta/models/x:generateContent", + ), +) +@pytest.mark.parametrize("method", (None, "GET", "HEAD", "POST", "DELETE", "get")) +def test_managed_actor_route_methods(route: str, method: str | None) -> None: + from litellm.proxy.agent_endpoints.auth.managed_authorization import managed_agent_route_allowed + + assert routes.classify_route(route_context(route, method), "Managed") == managed_agent_route_allowed(route, method) + + +@pytest.mark.parametrize( + ("key", "team", "jwt", "denied", "expected"), + ( + (("/p",), (), (), (), True), + ((), ("/p",), (), (), True), + (("/q",), ("/p",), (), (), False), + ((), (), ("/p/*",), (), True), + ((), (), ("*",), (), False), + (("/p",), (), (), ("/p",), False), + ), +) +def test_passthrough_precedence( + key: tuple[str, ...], team: tuple[str, ...], jwt: tuple[str, ...], denied: tuple[str, ...], expected: bool +) -> None: + facts: Final = routes.PassThroughFacts(key, team, denied, ("/p/resource",), jwt) + assert routes.passthrough_route(routes.RouteContext("/p/resource"), facts, required=True).allowed == expected