astral-sh/uv

uv-auth

crates/uv-auth/ is uv's credential layer. It collects credentials from URLs, environment variables, the keyring, and .netrc, caches them by realm, injects them into outgoing HTTP requests, and orchestrates trusted-publishing tokens for index access.

Purpose

uv talks to many indexes — public PyPI, private PyPI mirrors, private flat indexes, S3-style artifact stores. Each may require authentication. This crate centralizes the lookup so the HTTP client doesn't need to know about the various credential sources, and the resolver doesn't need to leak credentials when caching responses.

Directory layout

crates/uv-auth/src/
├── lib.rs              # Re-exports
├── service.rs          # Service: identifies an authenticated endpoint (URL + name)
├── realm.rs            # Realm: the (host, port, scheme) credential scope
├── credentials.rs      # Credentials: a username + password (or token) struct
├── access_token.rs     # AccessToken wrapper
├── cache.rs            # CredentialsCache: in-memory + on-disk credential cache
├── store.rs            # PyxTokenStore for OIDC-issued pyx tokens
├── keyring.rs          # KeyringProvider abstraction
├── middleware.rs       # 93k chars: the reqwest middleware that injects credentials
├── providers.rs        # AuthProviders: ordered list of providers (env, .netrc, keyring, …)
├── pyx.rs              # pyx-specific publishing/index auth
├── index.rs            # Per-index auth state
└── ...

Key abstractions

Type	File	Role
`Credentials`	`credentials.rs`	A username + secret (password or token). Implements `Display` to redact the secret.
`Realm`	`realm.rs`	The lookup scope: scheme + host + port. Two URLs share credentials if they have the same realm.
`Service`	`service.rs`	A logical endpoint the user authenticated to (e.g., a named index URL). Used by `uv auth login` and the auth helper.
`CredentialsCache`	`cache.rs`	In-memory LRU keyed by realm, with optional persistence for `uv auth`-managed credentials.
`KeyringProvider` (trait)	`keyring.rs`	Trait abstraction over OS keyrings. Concrete backends live in `uv-keyring`.
`AuthMiddleware`	`middleware.rs`	The reqwest middleware that wraps every request, picks credentials, retries with credentials on 401, and updates the cache.
`PyxTokenStore`	`store.rs`	Stores short-lived OIDC tokens issued by Astral's pyx for trusted publishing.
`Provider` (multiple)	`providers.rs`	Ordered providers tried in turn: URL-embedded, env-vars, `.netrc`, keyring, default.

How it works

flowchart LR
    request[Outgoing HTTP request] --> middleware[AuthMiddleware]
    middleware --> realm[Realm::from(url)]
    realm --> cache{CredentialsCache hit?}
    cache -- yes --> inject[Add Authorization header]
    cache -- no --> providers[Try providers in order]
    providers --> p1[URL embed]
    providers --> p2[Env vars: UV_INDEX_*_USERNAME/PASSWORD]
    providers --> p3[.netrc]
    providers --> p4[Keyring]
    providers --> p5[Trusted publishing]
    providers --> result{Found?}
    result -- yes --> store[CredentialsCache::store]
    store --> inject
    result -- no --> raw[Send unauthenticated]
    inject --> upstream[reqwest send]
    upstream --> resp{401?}
    resp -- yes, first attempt --> retry[Reload + retry once]
    resp -- success --> caller

Realms

A Realm is a (scheme, host, port) tuple. Credentials are scoped per-realm so that authentication to https://pypi.example.com:8080/simple/ doesn't leak to https://pypi.example.com/ (different port → different realm).

Providers

providers.rs defines an ordered list of AuthProviders. The default order is:

URL-embedded credentials. https://user:pass@host/path.
Environment variables. UV_INDEX_<NAME>_USERNAME, UV_INDEX_<NAME>_PASSWORD (named indexes); UV_PUBLISH_USERNAME/UV_PUBLISH_PASSWORD (publish).
.netrc. Read from $HOME/.netrc via the rust-netrc crate.
Keyring. When --keyring-provider is set to a concrete backend (subprocess, secret-service, etc.), this crate dispatches via the trait to uv-keyring.
Trusted publishing. OIDC token minting (crates/uv-auth/src/store.rs).

A failure of one provider falls through to the next.

Middleware

middleware.rs is the largest file in this crate (~93 KB) because it has to handle every edge case of authenticated HTTP:

Initial request decoration with cached credentials.
401 → reload the keyring (in case the user just stored credentials) and retry once.
Retry-with-credentials interactions with redirects across realms.
Adopted credentials promotion (a successful first request promotes the credentials in cache).
Streaming bodies (publish): the middleware avoids buffering the upload to retry.

`uv auth`

The uv auth namespace (crates/uv/src/commands/auth/) lets users login, logout, and inspect tokens. crates/uv-auth/src/service.rs and crates/uv-auth/src/cache.rs back the persistent store. uv auth helper is a credential-helper-style command so other tools (and git's credential.helper) can ask uv for credentials.

Integration points

uv-client wires this crate into the reqwest middleware stack.
uv-publish uses it for upload credentials and trusted-publishing tokens.
uv-keyring implements the keyring backends.
uv-redacted is used for any URL we display.
uv-git uses the credentials.rs types via its own credential helper integration.

Entry points for modification

Add a new credential source — implement an AuthProvider, register it in providers.rs. Decide its position carefully: providers earlier in the list win.
Tune retry semantics — middleware.rs. The "retry once on 401" logic is encoded there; changing it affects every request uv makes.
Add a new trusted-publishing flavor — extend store.rs and the publisher's TrustedPublishingService implementation.

Key source files

File	Purpose
`crates/uv-auth/src/credentials.rs`	The `Credentials` type (with redaction).
`crates/uv-auth/src/realm.rs`	Realm scoping.
`crates/uv-auth/src/cache.rs`	Per-realm cache.
`crates/uv-auth/src/middleware.rs`	The reqwest middleware.
`crates/uv-auth/src/keyring.rs`	The keyring trait abstraction.
`crates/uv-auth/src/providers.rs`	Provider ordering.
`crates/uv-auth/src/store.rs`	OIDC token store for pyx.