Skip to content
Merged
Show file tree
Hide file tree
Changes from 25 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
0de829d
feat(cli): store the lite login credential in the OS keychain
mateo-berri Aug 20, 2026
bd322ed
refactor(cli): state the credential-store precedence rules as contracts
mateo-berri Aug 20, 2026
01add58
fix(cli): name why a login fell back to the token file
mateo-berri Aug 20, 2026
65d834f
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri Aug 20, 2026
1750893
fix(cli): never report success while a credential is still readable
mateo-berri Aug 20, 2026
424e74b
fix(cli): roll the keychain write back when the plaintext copy cannot…
mateo-berri Aug 20, 2026
3c73a39
fix(cli): verify every credential store transition before reporting i…
mateo-berri Aug 20, 2026
26f6237
build: skip deleted files in the changed-file ruff format check
mateo-berri Aug 20, 2026
ba63755
fix(cli): keep lite login and logout honest when the keychain will no…
mateo-berri Aug 20, 2026
c7da91d
fix(cli): say so when the keychain took a credential the file cannot …
mateo-berri Aug 20, 2026
b6fef17
fix(cli): stop a repeat logout from retracting its own keychain warning
mateo-berri Aug 20, 2026
f86aeba
fix(cli): stop a file-held secret from vouching for an unreadable key…
mateo-berri Aug 20, 2026
ef104ac
fix(cli): report a token file logout cannot remove instead of crashing
mateo-berri Aug 20, 2026
4ca1f31
fix(cli): finish a refused token file rewrite in place
mateo-berri Aug 20, 2026
b142d1d
fix(cli): stop whoami calling an unreadable credential authenticated
mateo-berri Aug 20, 2026
fe11202
fix(cli): write the logout note again when the file holding it had to go
mateo-berri Aug 20, 2026
a2928ef
test(cli): cover the keyless token record and keep keyring to the cli…
Aug 20, 2026
5099379
fix(cli): stop asking a keychain that already stopped answering
Aug 20, 2026
71a5833
fix(cli): pick the credential by the sign-in it came from
mateo-berri Aug 20, 2026
b9ce630
docs(cli): say why a refused scrub does not roll the keychain back
mateo-berri Aug 20, 2026
a329dfb
fix(cli): keep each sign-in stamped past the one it replaces
Aug 20, 2026
8a8e8dc
docs(deps): say that the cli extra pulls cryptography on linux
Aug 20, 2026
fb69fcf
fix(cli): stamp each sign-in past the keychain as well as the file
mateo-berri Aug 20, 2026
1f2baf5
test(cli): model keyring's null backend in the vault test double
mateo-berri Aug 20, 2026
1fe06a1
test(cli): pin the shared stamp's effect on the freshness shortcut
mateo-berri Aug 20, 2026
5f7c0e1
Merge origin/litellm_internal_staging into litellm_cli_refresh_tokens
mateo-berri Aug 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -142,11 +142,13 @@ lint-install:
$(UV) sync --inexact --frozen --group proxy-dev --group e2e-dev
$(UV_RUN) python scripts/prisma_generate_if_needed.py

# Diff-scoped format check, identical to test-linting.yml's "Check ruff format" step:
# Diff-scoped format check, mirroring test-linting.yml's "Check ruff format" step:
# only the litellm Python files changed vs the base are checked, so a pre-existing
# format issue elsewhere doesn't block an unrelated commit.
# format issue elsewhere doesn't block an unrelated commit. Git pathspecs match
# recursively, so 'litellm/*.py' covers nested modules and the top-level files that
# CI's 'litellm/**/*.py' skips, which makes this target a superset of the CI step.
lint-format-check-changed: $(LINT_DEP_INSTALL) $(LINT_DEP_BASE)
@files=$$(git diff --name-only origin/litellm_internal_staging...HEAD -- 'litellm/**/*.py' | grep -v '^litellm/enterprise/' || true); \
@files=$$(git diff --name-only --diff-filter=ACMR origin/litellm_internal_staging...HEAD -- 'litellm/*.py' | grep -v '^litellm/enterprise/' || true); \
Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
if [ -z "$$files" ]; then \
echo "No changed litellm Python files to format-check."; \
else \
Expand Down
2 changes: 1 addition & 1 deletion cookbook/litellm_proxy_server/cli_token_usage.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,4 +60,4 @@ def main():
print("\n💡 Tips:")
print("1. Run 'litellm-proxy login' to authenticate first")
print("2. Replace 'https://your-proxy.com' with your actual proxy URL")
print("3. The token is stored locally at ~/.litellm/token.json")
print("3. The token is stored in your OS keychain, or in ~/.litellm/token.json when there is none")
231 changes: 231 additions & 0 deletions litellm/litellm_core_utils/cli_keyring.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,231 @@
"""
CLI Keyring Access

SDK-level access to the OS keychain (macOS Keychain, Windows Credential Manager,
Linux Secret Service) that holds the credential minted by `lite login`.

The `keyring` package is optional and imported lazily, so importing this module
never pulls it in. Every failure is returned as a value, naming which of the
ways the keychain can be out of reach applies, so callers can degrade to the
token file and tell the user what to do about it.

A write is only reported as stored once it has been read back, because keyring's
null backend, which `keyring --disable` and headless CI images both select,
accepts every write and keeps nothing. Writes are also pre-flighted with a
throwaway value, because a keychain can answer neither way and block forever.
"""
Comment thread
greptile-apps[bot] marked this conversation as resolved.
Resolved

import os
import threading
from contextlib import suppress
from dataclasses import dataclass, field
from typing import Final, Protocol, TypeAlias

KEYRING_SERVICE: Final = "litellm-cli"
KEYRING_ACCOUNT: Final = "credential"
KEYRING_PREFLIGHT_ACCOUNT: Final = "credential-preflight"
DISABLE_KEYRING_ENV_VAR: Final = "LITELLM_CLI_DISABLE_KEYRING"

_DISABLED_VALUES: Final = frozenset(("1", "true", "yes", "on"))
_PREFLIGHT_VALUE: Final = "preflight"
_PREFLIGHT_TIMEOUT_SECONDS: Final = 5.0


@dataclass(frozen=True, slots=True)
class SecretFound:
blob: str


@dataclass(frozen=True, slots=True)
class SecretMissing:
pass


@dataclass(frozen=True, slots=True)
class SecretStored:
pass


@dataclass(frozen=True, slots=True)
class SecretErased:
pass


@dataclass(frozen=True, slots=True)
class SecretStranded:
pass


@dataclass(frozen=True, slots=True)
class KeyringNotInstalled:
pass


@dataclass(frozen=True, slots=True)
class KeyringDisabled:
pass


@dataclass(frozen=True, slots=True)
class KeyringUnreachable:
pass


@dataclass(frozen=True, slots=True)
class KeyringDiscardsWrites:
pass


KeyringUnusable: TypeAlias = KeyringNotInstalled | KeyringDisabled | KeyringUnreachable
SecretRead: TypeAlias = SecretFound | SecretMissing | KeyringUnusable
SecretWrite: TypeAlias = SecretStored | KeyringUnusable | KeyringDiscardsWrites
SecretErase: TypeAlias = SecretErased | SecretStranded | KeyringUnusable


class SecretVault(Protocol):
"""The single slot holding the CLI credential's secret material."""

def read(self) -> SecretRead: ...

def write(self, blob: str) -> SecretWrite: ...

def erase(self) -> SecretErase: ...


class KeyringApi(Protocol):
def get_password(self, service_name: str, username: str) -> str | None: ...

def set_password(self, service_name: str, username: str, password: str) -> None: ...

def delete_password(self, service_name: str, username: str) -> None: ...


def _keyring_disabled() -> bool:
return os.getenv(DISABLE_KEYRING_ENV_VAR, "").strip().lower() in _DISABLED_VALUES


def _import_keyring() -> KeyringApi | None:
try:
import keyring
except ImportError:
return None
return keyring


def _keyring_api() -> KeyringApi | KeyringNotInstalled | KeyringDisabled:
if _keyring_disabled():
return KeyringDisabled()
api: Final = _import_keyring()
return KeyringNotInstalled() if api is None else api


def _answers_a_write(api: KeyringApi, timeout_seconds: float) -> bool:
"""Whether the keychain answers a write at all, asked with a value worth nothing.

macOS derives the login keychain from `$HOME`, and `set_password` against a HOME with no usable
one blocks forever with no timeout of its own. Containers, CI images, `sudo -H`, and service
accounts all run there, and reads answer normally, so nothing cheaper tells them apart. Asking
with a throwaway value keeps a keychain that never answers from taking `lite login` down with
it, and keeps the real credential out of a store that might accept it long after we gave up.
A keychain that refuses the probe outright still answered it, so only silence counts against it.
"""
answered: Final = threading.Event()

def ask() -> None:
with suppress(Exception):
api.set_password(KEYRING_SERVICE, KEYRING_PREFLIGHT_ACCOUNT, _PREFLIGHT_VALUE)
answered.set()

threading.Thread(target=ask, daemon=True, name="litellm-cli-keyring-preflight").start()
return answered.wait(timeout_seconds)


def _forget_the_preflight(api: KeyringApi) -> None:
"""Take the throwaway probe back out.

A backend that kept nothing has nothing to remove, and the probe is worth nothing either way,
so a keychain that refuses to give it up costs the caller nothing.
"""
with suppress(Exception):
api.delete_password(KEYRING_SERVICE, KEYRING_PREFLIGHT_ACCOUNT)


@dataclass(frozen=True, slots=True)
class KeyringVault:
"""The OS keychain, reached through the optional `keyring` package.

A keychain that let the pre-flight time out is not asked anything else for the rest of the
process. The probe that timed out is still sitting in the keychain on a thread of its own, and
it holds the keychain against every later call, so the read after it would block on the main
thread with no timeout to save it. One silence is answer enough.
"""

preflight_timeout_seconds: float = _PREFLIGHT_TIMEOUT_SECONDS
stopped_answering: threading.Event = field(default_factory=threading.Event, compare=False, repr=False)

def read(self) -> SecretRead:
if self.stopped_answering.is_set():
return KeyringUnreachable()
api: Final = _keyring_api()
if isinstance(api, (KeyringNotInstalled, KeyringDisabled)):
return api
try:
blob: Final = api.get_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
except Exception: # noqa: BLE001 # backends raise outside keyring.errors; never break the SDK
return KeyringUnreachable()
return SecretMissing() if blob is None else SecretFound(blob)

def write(self, blob: str) -> SecretWrite:
"""Store the secret, reporting stored only once the keychain hands the same bytes back.

A backend that accepts writes and keeps nothing, which is exactly what `keyring --disable`
and `PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring` select, raises nothing to
distinguish itself. Reading the value back is the only way to tell it apart from a keychain
that really stored the credential, and the caller is about to drop its own copy on our word.

The keychain is pre-flighted first, because one that blocks rather than answering would
otherwise hang `lite login` outright.
"""
if self.stopped_answering.is_set():
return KeyringUnreachable()
api: Final = _keyring_api()
if isinstance(api, (KeyringNotInstalled, KeyringDisabled)):
return api
if not _answers_a_write(api, self.preflight_timeout_seconds):
self.stopped_answering.set()
return KeyringUnreachable()
_forget_the_preflight(api)
try:
api.set_password(KEYRING_SERVICE, KEYRING_ACCOUNT, blob)
except Exception: # noqa: BLE001 # a keychain that refuses the write falls back to the token file
return KeyringUnreachable()
return SecretStored() if self.read() == SecretFound(blob) else KeyringDiscardsWrites()

def erase(self) -> SecretErase:
"""Remove our entry, reporting whether the keychain is guaranteed to be free of it.

A keychain out of reach is never an erasure: the entry belongs to the OS, not to this
install, so it outlives an uninstalled `keyring` package and a kill switch set after login.
Those cases are reported apart from a confirmed entry that would not delete, because only
the caller knows whether this machine ever put a secret in a keychain.
"""
match self.read():
case KeyringNotInstalled() | KeyringDisabled() | KeyringUnreachable() as unusable:
return unusable
case SecretMissing():
return SecretErased()
case SecretFound():
return self._delete()

def _delete(self) -> SecretErase:
api: Final = _keyring_api()
if isinstance(api, (KeyringNotInstalled, KeyringDisabled)):
return api
try:
api.delete_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
except Exception: # noqa: BLE001 # report the failure as a value so `lite logout` can warn
return SecretStranded()
return SecretErased()


SYSTEM_KEYRING: Final[SecretVault] = KeyringVault()
Loading
Loading