diff --git a/litellm/proxy/client/cli/README.md b/litellm/proxy/client/cli/README.md index 842705ad5a7..934fecb1028 100644 --- a/litellm/proxy/client/cli/README.md +++ b/litellm/proxy/client/cli/README.md @@ -506,7 +506,7 @@ To pin the model, pass the agent's own model flag (for example `lite claude --mo The token minted by `lite login` is a short-lived, per-session agent credential, not a managed virtual key. It is scoped to the user and team you authenticated as, inherits that user's and team's models and budgets, and is enforced on the proxy exactly like a virtual key on the same team (guardrails, routing, logging, spend). Spend is tracked against the shared team and user budgets, so running several agents (or logging in more than once) does not hand each session its own separate budget; they all draw down the same team/user allowance. There is no separate per-session cap, so sustained agent use is not capped at a small chat-session limit. -The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it while it's still fresh and fails once it expires -- there is no silent renewal, so a long-running session needs a fresh `lite login` once a day. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the daily re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead. +The credential is short-lived by design (default 24h, configurable via `LITELLM_CLI_JWT_EXPIRATION_HOURS`); run `lite login` again to refresh it, which also re-reads your latest team and user settings. It does not appear in the Keys UI and cannot be rotated or revoked mid-session. `lite auth print-token` (usable as Claude Code's `apiKeyHelper`) prints it until the proxy stops accepting it and then fails -- there is no silent renewal, so a long-running session needs a fresh `lite login` each time the proxy's token lifetime runs out. Past 24 hours, or `LITELLM_CLI_JWT_EXPIRATION_HOURS` if you set it on the client, `print-token`, `lite whoami`, and `lite up` ask the proxy whether it still accepts the token instead of assuming it expired. `lite claude`, `lite codex`, `lite opencode`, and `lite pi` work with it on a default deployment; `EXPERIMENTAL_UI_LOGIN` is not required. `lite login --pkce` is the exception to the re-login: it signs in through your system browser with OAuth authorization code and PKCE and stores a refresh token next to the key, so every `lite` command and `lite auth print-token` renew the key on their own shortly before it expires, `lite whoami` shows when the current key expires, and `lite logout` revokes the refresh token on the proxy (it needs a proxy that serves `/.well-known/litellm-cli-auth`; see [Browser sign-in with PKCE](https://docs.litellm.ai/docs/proxy/cli_sso#browser-sign-in-with-pkce)). When a renewal is refused, for example after a `lite logout` run from another copy of the credential, the command prints why on stderr and, once the key has run out, tells you to run `lite login --pkce` again. Only the holder can end a `--pkce` session early, with `lite logout`; an admin has no button for it, but every renewal re-reads the user on the proxy, so deactivating the user or removing them from the team makes the next renewal fail and the key runs out within `LITELLM_CLI_JWT_EXPIRATION_HOURS`. On a proxy with more than one worker or replica, configure Redis (`litellm_settings.cache` with Redis `cache_params`, or `general_settings.coordination_redis`) so a refresh token stays single-use and `lite logout` holds on every worker; without Redis each worker keeps its own record. If you need a long-lived, rotatable key that shows up in the Keys UI, create a dedicated virtual key in the dashboard and pass it via `--api-key` or `LITELLM_PROXY_API_KEY` instead. ### Route Every Claude Code Session Through the Proxy diff --git a/litellm/proxy/client/cli/commands/auth.py b/litellm/proxy/client/cli/commands/auth.py index 2b6289234d4..fb00e02dbdd 100644 --- a/litellm/proxy/client/cli/commands/auth.py +++ b/litellm/proxy/client/cli/commands/auth.py @@ -143,6 +143,7 @@ _TeamMapping: Final = TypeVar("_TeamMapping", bound=Mapping[str, object]) _JSON_OBJECT: Final = TypeAdapter(Mapping[str, object], config=ConfigDict(hide_input_in_errors=True)) _PROXY_KEY_CHECK_TIMEOUT_SECONDS: Final = 10 +_PROXY_REJECTED_KEY_STATUSES: Final = frozenset({401, 403, 404}) KEYRING_INSTALL_HINT: Final = "pip install 'litellm[cli]'" @@ -1058,7 +1059,7 @@ def print_token(ctx: click.Context): sys.exit(1) renews: Final = "refresh_token" in token_data - if not renews and _token_expired(token_data): + if not renews and token_expired(token_data): click.echo("Token expired. Run 'lite login' again.", err=True) sys.exit(1) @@ -1114,11 +1115,11 @@ def whoami(ctx: click.Context): expires_at: Final = token_data.get("expires_at") if isinstance(expires_at, (int, float)): click.echo(_key_expiry_line(expires_at, renews="refresh_token" in token_data)) - elif _token_expired(token_data): + elif token_expired(token_data): click.echo("Token expired. Run 'lite login' again.") -def _token_expired(token_data: Mapping[str, object]) -> bool: +def token_expired(token_data: Mapping[str, object]) -> bool: if is_cli_token_fresh(token_data): return False if isinstance(token_data.get("expires_at"), (int, float)): @@ -1139,7 +1140,7 @@ def _proxy_rejects_key(token_data: Mapping[str, object]) -> bool: ) except requests.RequestException: return False - return response.status_code == 401 + return response.status_code in _PROXY_REJECTED_KEY_STATUSES def _key_expiry_line(expires_at: float, renews: bool) -> str: diff --git a/litellm/proxy/client/cli/commands/up.py b/litellm/proxy/client/cli/commands/up.py index 4043761f255..0c4e9bdcf25 100644 --- a/litellm/proxy/client/cli/commands/up.py +++ b/litellm/proxy/client/cli/commands/up.py @@ -15,11 +15,18 @@ import click from pydantic import JsonValue, TypeAdapter, ValidationError from litellm.litellm_core_utils.cli_keyring import SecretVault -from litellm.litellm_core_utils.cli_token_utils import is_cli_token_fresh from litellm.litellm_core_utils.private_json import ensure_private_dir from .agents import AgentRunError, resolve_api_key, verify_proxy_key -from .auth import CliContextObj, cli_context_obj, context_secret_vault, get_stored_api_key, load_token, login +from .auth import ( + CliContextObj, + cli_context_obj, + context_secret_vault, + get_stored_api_key, + load_token, + login, + token_expired, +) from .claude_settings import ( BACKUP_PATH, CLAUDE_SETTINGS_PATH, @@ -111,7 +118,7 @@ def _usable_login(api_key: str | None, vault: SecretVault) -> bool: if api_key is None: return False token_data: Final = load_token(vault=vault) - return token_data is not None and is_cli_token_fresh(token_data) + return token_data is not None and not token_expired(token_data) def _key_resolved_on_the_way_in(ctx_obj: CliContextObj, base_url: str, vault: SecretVault) -> str | None: diff --git a/tests/unit/proxy/client/cli/test_auth_commands.py b/tests/unit/proxy/client/cli/test_auth_commands.py index d3f87d852cc..cf01954c223 100644 --- a/tests/unit/proxy/client/cli/test_auth_commands.py +++ b/tests/unit/proxy/client/cli/test_auth_commands.py @@ -3,6 +3,7 @@ import os import stat import time from pathlib import Path +from typing import Final from unittest.mock import Mock, patch import pytest @@ -58,12 +59,12 @@ def _write_token_file(home: Path, *, key: str | None) -> None: _write_home_json(home, "token.json", payload if key is None else {**payload, "key": key}) -STALE_TOKEN_BASE_URL = "https://stale-token.example.com" +STALE_TOKEN_BASE_URL: Final = "https://stale-token.example.com" def _register_models_answer(key: str, answer: int | Exception) -> None: - models_url = f"{STALE_TOKEN_BASE_URL}/v1/models" - authorized = [matchers.header_matcher({"Authorization": f"Bearer {key}"})] + models_url: Final = f"{STALE_TOKEN_BASE_URL}/v1/models" + authorized: Final = [matchers.header_matcher({"Authorization": f"Bearer {key}"})] if isinstance(answer, Exception): responses.get(models_url, body=answer, match=authorized) else: @@ -719,9 +720,11 @@ class TestWhoamiCommand: ], ) @responses.activate - def test_whoami_lets_the_proxy_judge_a_token_older_than_the_client_window(self, proxy_status, expected_last_line): + def test_whoami_lets_the_proxy_judge_a_token_older_than_the_client_window( + self, proxy_status: int, expected_last_line: str + ): _register_models_answer("sk-live", proxy_status) - token_data = CliTokenRecord( + token_data: Final = CliTokenRecord( base_url=STALE_TOKEN_BASE_URL, user_email="test@example.com", key="sk-live", @@ -729,7 +732,7 @@ class TestWhoamiCommand: ) with patch("litellm.proxy.client.cli.commands.auth.load_cli_token", return_value=token_data): - result = self.runner.invoke(whoami) + result: Final = self.runner.invoke(whoami) assert result.exit_code == 0 assert result.output.splitlines()[-1] == expected_last_line @@ -1060,7 +1063,7 @@ class TestPrintTokenCommand: timestamp=time.time(), ), ): - result = self.runner.invoke(print_token, obj={}) + result: Final = self.runner.invoke(print_token, obj={}) assert result.exit_code == 0 assert result.output.strip() == "sk-cached-fresh" @@ -1071,13 +1074,19 @@ class TestPrintTokenCommand: [ (200, 0, "sk-stale-key\n", ""), (401, 1, "", "Token expired. Run 'lite login' again.\n"), + (403, 1, "", "Token expired. Run 'lite login' again.\n"), + (404, 1, "", "Token expired. Run 'lite login' again.\n"), (500, 0, "sk-stale-key\n", ""), (requests.ConnectionError("proxy unreachable"), 0, "sk-stale-key\n", ""), ], ) @responses.activate def test_key_older_than_the_client_window_is_judged_by_the_proxy( - self, proxy_answer, expected_exit_code, expected_stdout, expected_stderr + self, + proxy_answer: int | Exception, + expected_exit_code: int, + expected_stdout: str, + expected_stderr: str, ): _register_models_answer("sk-stale-key", proxy_answer) @@ -1089,7 +1098,7 @@ class TestPrintTokenCommand: timestamp=time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, ), ): - result = self.runner.invoke(print_token, obj={}) + result: Final = self.runner.invoke(print_token, obj={}) assert result.exit_code == expected_exit_code assert result.stdout == expected_stdout @@ -2060,7 +2069,7 @@ class TestPkcePrintToken: ), patch("litellm.proxy.client.cli.commands.auth.requests.Session", _FakeSession), ): - result = self.runner.invoke(print_token, obj={}) + result: Final = self.runner.invoke(print_token, obj={}) assert result.exit_code == 1 assert result.stdout == "" diff --git a/tests/unit/proxy/client/cli/test_up_commands.py b/tests/unit/proxy/client/cli/test_up_commands.py index 5c2e726315b..99af1f36867 100644 --- a/tests/unit/proxy/client/cli/test_up_commands.py +++ b/tests/unit/proxy/client/cli/test_up_commands.py @@ -3,12 +3,15 @@ import shutil import stat import sys import time +from typing import Final from unittest.mock import patch import click import pytest +import responses from click.testing import CliRunner +from litellm.constants import CLI_JWT_EXPIRATION_HOURS from litellm.proxy.client.cli.commands import up as up_module from litellm.proxy.client.cli.commands.agents import AgentRunError from litellm.proxy.client.cli.commands.claude_settings import ClaudeSettingsError, StaticToken @@ -302,7 +305,7 @@ class TestEnsureFreshLogin: _FakeTokenStore( monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {"http://proxy-a:4000": "sk-a"} ) - monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) + monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) login_calls = _capture_login(monkeypatch) ensure_fresh_login(_make_ctx("http://proxy-a:4000")) @@ -312,7 +315,7 @@ class TestEnsureFreshLogin: def test_forces_a_fresh_login_when_the_cached_token_is_for_a_different_proxy(self, monkeypatch): monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True) store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {}) - monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) + monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) login_calls = _capture_login( monkeypatch, on_login=lambda: store.log_in({"key": "sk-b", "base_url": "http://proxy-b:4000"}, "sk-b") ) @@ -325,7 +328,7 @@ class TestEnsureFreshLogin: def test_forces_a_fresh_login_when_the_cached_token_has_no_readable_key(self, monkeypatch): monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True) store = _FakeTokenStore(monkeypatch, {"base_url": "http://proxy-a:4000"}, {}) - monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) + monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) login_calls = _capture_login( monkeypatch, on_login=lambda: store.log_in({"key": "sk-a", "base_url": "http://proxy-a:4000"}, "sk-a"), @@ -338,11 +341,38 @@ class TestEnsureFreshLogin: def test_fails_cleanly_non_interactively_when_only_a_different_proxys_token_is_cached(self, monkeypatch): monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False) _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {}) - monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) + monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) with pytest.raises(UpError, match="Run `lite login` first"): ensure_fresh_login(_make_ctx("http://proxy-b:4000")) + @pytest.mark.parametrize(("proxy_status", "expected_login_calls"), [(200, []), (401, [("http://proxy-a:4000", False)])]) + @responses.activate + def test_lets_the_proxy_judge_a_classic_token_older_than_the_client_window( + self, monkeypatch, proxy_status: int, expected_login_calls: list[tuple[str, bool]] + ): + monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True) + responses.get("http://proxy-a:4000/v1/models", json={"data": []}, status=proxy_status) + store: Final = _FakeTokenStore( + monkeypatch, + { + "key": "sk-a", + "base_url": "http://proxy-a:4000", + "timestamp": time.time() - (CLI_JWT_EXPIRATION_HOURS + 1) * 3600, + }, + {"http://proxy-a:4000": "sk-a"}, + ) + login_calls: Final = _capture_login( + monkeypatch, + on_login=lambda: store.log_in( + {"key": "sk-new", "base_url": "http://proxy-a:4000", "timestamp": time.time()}, "sk-new" + ), + ) + + ensure_fresh_login(_make_ctx("http://proxy-a:4000")) + + assert login_calls == expected_login_calls + def test_trusts_a_pkce_credential_that_was_renewed_on_the_way_in(self, monkeypatch): """A --pkce key inside its freshness buffer is renewed by `get_stored_api_key`, so `lite up` must judge the rotated record rather than refuse the one it started with.""" @@ -376,7 +406,7 @@ class TestEnsureFreshLogin: """`lite config set pkce true` is honoured by the login `lite up` starts, not only by `lite login`.""" monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: True) store = _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {}) - monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) + monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) monkeypatch.setattr(up_module, "pkce_default", lambda: True) login_calls = _capture_login( monkeypatch, @@ -390,7 +420,7 @@ class TestEnsureFreshLogin: def test_names_the_pkce_login_in_the_non_interactive_error_when_the_saved_pkce_default_is_on(self, monkeypatch): monkeypatch.setattr(up_module.sys.stdin, "isatty", lambda: False) _FakeTokenStore(monkeypatch, {"key": "sk-a", "base_url": "http://proxy-a:4000"}, {}) - monkeypatch.setattr(up_module, "is_cli_token_fresh", lambda token_data: True) + monkeypatch.setattr(up_module, "token_expired", lambda token_data: False) monkeypatch.setattr(up_module, "pkce_default", lambda: True) with pytest.raises(UpError, match="Run `lite login --pkce` first"): @@ -455,7 +485,7 @@ class TestUpCommand: with ( patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}), patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"), - patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True), + patch(f"{UP_MODULE}.token_expired", return_value=False), patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"), patch(f"{UP_MODULE}.verify_proxy_key"), ): @@ -486,7 +516,7 @@ class TestUpCommand: with ( patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}), patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"), - patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True), + patch(f"{UP_MODULE}.token_expired", return_value=False), patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"), patch( f"{UP_MODULE}.verify_proxy_key", @@ -515,7 +545,7 @@ class TestUpCommand: with ( patch(f"{UP_MODULE}.load_token", return_value={"key": "sk-fresh", "base_url": "http://localhost:4000"}), patch(f"{UP_MODULE}.get_stored_api_key", return_value="sk-fresh"), - patch(f"{UP_MODULE}.is_cli_token_fresh", return_value=True), + patch(f"{UP_MODULE}.token_expired", return_value=False), patch(f"{UP_MODULE}.resolve_api_key", return_value="sk-fresh"), patch(f"{UP_MODULE}.verify_proxy_key"), patch(f"{UP_MODULE}.signal.signal"),