Repository navigation
feat(cli): store the lite login credential in the OS keychain #37566
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
mateo-berri
merged 26 commits into
litellm_internal_staging
from
litellm_cli_refresh_tokens
Aug 20, 2026
Merged
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 bd322ed
refactor(cli): state the credential-store precedence rules as contracts
mateo-berri 01add58
fix(cli): name why a login fell back to the token file
mateo-berri 65d834f
Merge remote-tracking branch 'origin/litellm_internal_staging' into l…
mateo-berri 1750893
fix(cli): never report success while a credential is still readable
mateo-berri 424e74b
fix(cli): roll the keychain write back when the plaintext copy cannot…
mateo-berri 3c73a39
fix(cli): verify every credential store transition before reporting i…
mateo-berri 26f6237
build: skip deleted files in the changed-file ruff format check
mateo-berri ba63755
fix(cli): keep lite login and logout honest when the keychain will no…
mateo-berri c7da91d
fix(cli): say so when the keychain took a credential the file cannot …
mateo-berri b6fef17
fix(cli): stop a repeat logout from retracting its own keychain warning
mateo-berri f86aeba
fix(cli): stop a file-held secret from vouching for an unreadable key…
mateo-berri ef104ac
fix(cli): report a token file logout cannot remove instead of crashing
mateo-berri 4ca1f31
fix(cli): finish a refused token file rewrite in place
mateo-berri b142d1d
fix(cli): stop whoami calling an unreadable credential authenticated
mateo-berri fe11202
fix(cli): write the logout note again when the file holding it had to go
mateo-berri a2928ef
test(cli): cover the keyless token record and keep keyring to the cli…
5099379
fix(cli): stop asking a keychain that already stopped answering
71a5833
fix(cli): pick the credential by the sign-in it came from
mateo-berri b9ce630
docs(cli): say why a refused scrub does not roll the keychain back
mateo-berri a329dfb
fix(cli): keep each sign-in stamped past the one it replaces
8a8e8dc
docs(deps): say that the cli extra pulls cryptography on linux
fb69fcf
fix(cli): stamp each sign-in past the keychain as well as the file
mateo-berri 1f2baf5
test(cli): model keyring's null backend in the vault test double
mateo-berri 1fe06a1
test(cli): pin the shared stamp's effect on the freshness shortcut
mateo-berri 5f7c0e1
Merge origin/litellm_internal_staging into litellm_cli_refresh_tokens
mateo-berri File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
| """ | ||
|
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() | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.