Skip to main content

drep/
auth.rs

1//! The credential store: API keys drep holds on the user's behalf.
2//!
3//! `drep.toml` is a repository file. It names an endpoint, a model and a
4//! protocol, all of which are shareable, and it is meant to survive being
5//! committed - which is why `api_key = "${VAR}"` names an environment variable
6//! rather than holding a secret. That indirection is the right answer for CI,
7//! where the key arrives as a secret and nobody is at a keyboard, and the wrong
8//! answer for a person setting drep up on their laptop: it makes the first-run
9//! experience "now go and export something into the right shell profile".
10//!
11//! So keys live here instead, once per machine, outside any repository:
12//!
13//! ```text
14//! ~/.config/drep/auth.toml     (macOS: ~/Library/Application Support/dev.slb350.drep)
15//! ```
16//!
17//! ## Keyed by endpoint, not by provider name
18//!
19//! A key authenticates a *host*, so the endpoint is what it belongs to. Keying
20//! by a preset name instead would mean a config that named no preset - a custom
21//! endpoint, or one edited by hand after `drep init` - could not find its own
22//! credential, and two presets pointed at the same host would each need their
23//! own copy of one key.
24//!
25//! The endpoint is normalised before use (see [`normalise`]) so a trailing
26//! slash or a difference in case does not hide a key from the config that
27//! stored it.
28//!
29//! There is deliberately no `load_default`/`save_default` pair. Both were thin
30//! wrappers over `default_path()`, which reads the environment - so nothing
31//! could test them without `std::env::set_var`, and the mutation gate found
32//! them undetectable. Every caller resolves the path once, at its own entry
33//! point, and passes it down; that is also what keeps tests off the real store.
34//!
35//! ## Resolution order
36//!
37//! [`resolve`] fills in what `drep.toml` left unset, in this order:
38//!
39//! 1. an explicit `api_key` - a literal, or a `${VAR}` the loader has already
40//!    substituted;
41//! 2. `api_key_command`, an argv drep runs to mint one;
42//! 3. a key held here for the same endpoint;
43//! 4. nothing, which `LlmClient::new` turns into an empty key so the SDK sends
44//!    no protocol authentication header.
45//!
46//! An explicit value in the file always wins. A user who writes
47//! `api_key = "${OPENROUTER_API_KEY}"` has said where the key comes from, and
48//! silently preferring a stored one would make the file lie about what the run
49//! used. The command sits above the store for the same reason: a file naming a
50//! command has not left the question unanswered.
51
52use std::collections::{BTreeMap, BTreeSet};
53use std::path::PathBuf;
54
55use serde::{Deserialize, Serialize};
56use thiserror::Error;
57
58use crate::config::Config;
59
60mod command;
61mod store_file;
62pub use command::KeyCommandError;
63pub(crate) use store_file::ensure_dir_private;
64#[cfg(test)]
65pub(crate) use store_file::{restrict, temporary_parent};
66
67/// Where a provider's key came from, for [`doctor`](crate::cli::doctor) to report.
68///
69/// The point of naming the source is that "it works on my machine" and "it works
70/// in CI" are different configurations, and the difference is invisible in
71/// `drep.toml` once a stored key exists.
72///
73/// The variant order is the resolution order.
74#[derive(Debug, Clone, PartialEq, Eq)]
75pub enum KeySource {
76    /// The config named an environment variable or a literal, and it resolved.
77    Config,
78    /// The config named an `api_key_command`, which drep runs to mint a key.
79    Command,
80    /// The config named nothing and the store had one for this endpoint.
81    Store,
82    /// Neither. The provider sends no protocol authentication header; a custom
83    /// header may still provide the endpoint's complete authentication scheme.
84    Missing,
85}
86
87impl KeySource {
88    /// Every source, in resolution order.
89    ///
90    /// Exists so the label-collision test cannot pass on a stale subset, the way
91    /// `Severity::ALL` drives its parser test: a variant added without wording of
92    /// its own has to fail something.
93    pub const ALL: [Self; 4] = [Self::Config, Self::Command, Self::Store, Self::Missing];
94
95    /// What `doctor` prints for this source.
96    ///
97    /// The single definition of the wording. `doctor` hand-wrote its own copy
98    /// of these three strings while this method sat unused, which is two places
99    /// to keep in step for no gain.
100    pub fn label(&self) -> &'static str {
101        match self {
102            Self::Config => "from drep.toml",
103            Self::Command => "from api_key_command",
104            Self::Store => "from the drep auth store",
105            Self::Missing => "not set - run `drep auth login` or add `api_key` to drep.toml",
106        }
107    }
108}
109
110/// Keys held for this machine, keyed by normalised endpoint.
111///
112/// `Serialize`/`Deserialize` drive the on-disk TOML directly; there is no
113/// separate wire type because the file is drep's own and has one shape.
114#[derive(Default, Serialize, Deserialize)]
115pub struct AuthStore {
116    /// Endpoint to key. A `BTreeMap` so the file is written in a stable order
117    /// and a re-save produces no spurious diff.
118    #[serde(default)]
119    keys: BTreeMap<String, String>,
120
121    /// Mutations made since this snapshot was loaded.
122    ///
123    /// Saving replays only these operations over the latest on-disk store, so
124    /// two drep processes changing different endpoints cannot overwrite one
125    /// another. The journal is process state, never part of the TOML file.
126    #[serde(skip)]
127    pending: std::sync::Mutex<BTreeSet<String>>,
128}
129
130/// Hand-written so a key cannot reach a log.
131///
132/// The same reasoning as `LlmConfig` and `LlmClient`: a derived `Debug` prints
133/// every value, so one `{:?}` anywhere would emit every credential the user has.
134/// The endpoints are printed because they are not secret and they are the useful
135/// half when debugging.
136impl std::fmt::Debug for AuthStore {
137    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
138        f.debug_struct("AuthStore")
139            .field("endpoints", &self.keys.keys().collect::<Vec<_>>())
140            .finish()
141    }
142}
143
144/// What can go wrong reading or writing the store.
145#[derive(Debug, Error)]
146pub enum AuthError {
147    #[error("no config directory for this platform; set the key in drep.toml instead")]
148    NoConfigDir,
149
150    #[error("could not read {0}: {1}")]
151    Read(PathBuf, std::io::Error),
152
153    #[error("could not write {0}: {1}")]
154    Write(PathBuf, std::io::Error),
155
156    #[error("could not lock auth store {0}: {1}")]
157    Lock(PathBuf, std::io::Error),
158
159    #[error("could not parse {0}: {1}")]
160    Parse(PathBuf, String),
161
162    /// Serializing the store failed. Distinct from [`Self::Parse`], which is
163    /// about reading: a write failure reported as "could not parse" sends the
164    /// reader looking at the file rather than at what drep tried to write.
165    #[error("could not serialize the auth store: {0}")]
166    Serialize(String),
167
168    #[error("refusing to store an empty key for {0}")]
169    EmptyKey(String),
170
171    /// A key carrying a control character cannot be sent as an HTTP header, so
172    /// storing it would defer a guaranteed failure to the first request.
173    #[error("the key for {0} contains a character that cannot be sent in a header")]
174    UnusableKey(String),
175
176    /// A configured `api_key_command` did not produce a credential.
177    ///
178    /// Fatal, and fatal *here*: the provider chain does not exist yet, so there
179    /// is nothing to fail over to - and failing over would be the wrong answer
180    /// anyway, for the reason a 401 does not fail over. Routing around a broken
181    /// credential path is what hides it.
182    ///
183    /// The entry is numbered in file order, matching `ConfigError`, because that
184    /// is the numbering a user can count blocks in `drep.toml` to check.
185    #[error("[[llm]] #{} in file order: {cause}", index + 1)]
186    KeyCommand {
187        index: usize,
188        cause: KeyCommandError,
189    },
190}
191
192/// The environment variable that relocates the store.
193pub const PATH_VAR: &str = "DREP_AUTH_PATH";
194
195/// The store location: [`PATH_VAR`] if set, else the platform's config dir.
196///
197/// The platform path comes from `directories::ProjectDirs` with the same triple
198/// `Cache::default_root` uses, so drep's two user-level directories are siblings
199/// under one application identity rather than two unrelated paths.
200///
201/// The override exists because there is otherwise **no way to run drep against a
202/// scratch store**. `directories` follows each platform's own convention rather
203/// than the XDG variables, so on macOS `XDG_CONFIG_HOME` is ignored entirely and
204/// a command run to try something out writes into the real store - which is how
205/// a test key ended up in one. It also serves the ordinary case of keeping
206/// credentials somewhere deliberate, such as a mounted volume.
207pub fn default_path() -> Result<PathBuf, AuthError> {
208    path_from(std::env::var_os(PATH_VAR))
209}
210
211/// [`default_path`] with the override supplied rather than read.
212///
213/// Split out so the override can be tested without writing to the process
214/// environment. `std::env::set_var` is `unsafe` in edition 2024 because another
215/// thread reading the environment concurrently is a data race, and `cargo test`
216/// runs tests on several threads - a "single-threaded test process" safety
217/// comment would simply have been untrue.
218pub fn path_from(overridden: Option<std::ffi::OsString>) -> Result<PathBuf, AuthError> {
219    if let Some(path) = overridden {
220        return Ok(PathBuf::from(path));
221    }
222    directories::ProjectDirs::from("dev", "slb350", "drep")
223        .map(|dirs| dirs.config_dir().join("auth.toml"))
224        .ok_or(AuthError::NoConfigDir)
225}
226
227impl AuthStore {
228    /// An empty store, for a machine that has never stored a key.
229    pub fn new() -> Self {
230        Self::default()
231    }
232
233    /// The key held for `endpoint`, if any.
234    pub fn get(&self, endpoint: &str) -> Option<&str> {
235        self.keys.get(&normalise(endpoint)).map(String::as_str)
236    }
237
238    /// Store `key` for `endpoint`, replacing any previous one.
239    ///
240    /// The rule about what a credential may be is `vet`'s, not this method's;
241    /// only the wording is here, because a paste at the prompt and a helper's
242    /// stdout send the reader to different fixes.
243    pub fn set(&mut self, endpoint: &str, key: &str) -> Result<(), AuthError> {
244        let key = vet(key).map_err(|defect| match defect {
245            CredentialDefect::Empty => AuthError::EmptyKey(endpoint.to_string()),
246            CredentialDefect::Unusable => AuthError::UnusableKey(endpoint.to_string()),
247        })?;
248        let endpoint = normalise(endpoint);
249        self.keys.insert(endpoint.clone(), key);
250        self.pending
251            .get_mut()
252            .unwrap_or_else(std::sync::PoisonError::into_inner)
253            .insert(endpoint);
254        Ok(())
255    }
256
257    /// Forget the key for `endpoint`. Returns whether one was held.
258    pub fn remove(&mut self, endpoint: &str) -> bool {
259        let endpoint = normalise(endpoint);
260        let removed = self.keys.remove(&endpoint).is_some();
261        if removed {
262            self.pending
263                .get_mut()
264                .unwrap_or_else(std::sync::PoisonError::into_inner)
265                .insert(endpoint);
266        }
267        removed
268    }
269
270    /// Every endpoint with a stored key, in sorted order. Never the keys.
271    pub fn endpoints(&self) -> Vec<&str> {
272        self.keys.keys().map(String::as_str).collect()
273    }
274
275    /// Whether the store holds nothing.
276    pub fn is_empty(&self) -> bool {
277        self.keys.is_empty()
278    }
279}
280
281/// Why a credential cannot be used, whatever produced it.
282///
283/// Two variants because they send the reader to different fixes: nothing arrived
284/// at all, or something arrived that cannot be sent.
285pub(crate) enum CredentialDefect {
286    Empty,
287    Unusable,
288}
289
290/// Trim a candidate credential and refuse one that cannot become a header value.
291///
292/// One definition, because this is a safety property, and `crate::http`'s module
293/// doc already records what happens to a safety property written twice: "written
294/// once and forgotten once". It was written twice - here for a key pasted at the
295/// prompt, and in `auth::command::run` for one a helper printed - and the two
296/// copies had already drifted cosmetically. The minted path is the one that never
297/// passes through [`AuthStore::set`], so a defect class added at the prompt would
298/// silently not have applied to the credential a gateway helper produces, which is
299/// the only path whose value nobody ever sees.
300///
301/// The wording stays with each caller: this returns [`CredentialDefect`] rather
302/// than an `AuthError`, so the store can name the endpoint and the helper can name
303/// the program. That is the mechanism-shared, classification-private split
304/// `crate::http` documents for the same pair of callers.
305///
306/// **Both ends** are trimmed. Every helper that prints a token prints a newline
307/// after it, and a leading space is one `printf ' %s'` or one `cut` field away;
308/// trimming only the tail accepted `" sk-live-..."`, which passes the
309/// control-character guard and is then stripped again by the transport, so the
310/// value sent was not the value checked and the endpoint answered 401.
311///
312/// A control character is refused because every use of a credential is an HTTP
313/// header value, which cannot carry one. Rejecting it here turns a paste or a
314/// helper that picked up a stray escape sequence into a message the user can act
315/// on, rather than a transport failure on the first file of the first push.
316pub(crate) fn vet(candidate: &str) -> Result<String, CredentialDefect> {
317    let candidate = candidate.trim();
318    if candidate.is_empty() {
319        return Err(CredentialDefect::Empty);
320    }
321    if candidate.chars().any(char::is_control) {
322        return Err(CredentialDefect::Unusable);
323    }
324    Ok(candidate.to_owned())
325}
326
327/// Canonical form of an endpoint for use as a store key.
328///
329/// Lowercased and stripped of trailing slashes. `https://API.Z.AI/v1/` and
330/// `https://api.z.ai/v1` are the same host and the same credential, and a store
331/// that disagreed would report "no key" for a config that had just stored one -
332/// a failure with no visible cause, since both spellings look right.
333///
334/// Deliberately no more than that: the path is significant (`/v1` and
335/// `/anthropic/v1` are different APIs on the same host, and can carry different
336/// keys), so nothing beyond the trailing slash is trimmed.
337pub fn normalise(endpoint: &str) -> String {
338    let trimmed = endpoint.trim().trim_end_matches('/');
339
340    // Only the scheme and authority are case-insensitive; a URL *path* is not.
341    // Lowercasing the whole thing collapsed `/API/v1` and `/api/v1` onto one
342    // entry, which for a host serving both would hand one endpoint's key to the
343    // other - the same class of mistake as keying on the model alone.
344    match trimmed.find("://") {
345        Some(scheme_end) => format!(
346            "{}://{}",
347            trimmed[..scheme_end].to_ascii_lowercase(),
348            lower_authority(&trimmed[scheme_end + 3..])
349        ),
350        // No scheme, which is what `localhost:11434/v1` looks like. It still has
351        // an authority and a path, and the same rule applies to both halves -
352        // lowercasing the whole string collapsed `/V1` onto `/v1` for exactly
353        // the endpoints a user is most likely to type by hand.
354        None => lower_authority(trimmed),
355    }
356}
357
358/// Lowercase everything before the first `/` and leave the rest alone.
359fn lower_authority(rest: &str) -> String {
360    let host_len = rest.find('/').unwrap_or(rest.len());
361    format!(
362        "{}{}",
363        rest[..host_len].to_ascii_lowercase(),
364        &rest[host_len..]
365    )
366}
367
368/// Fill in keys the config left unset, and report where each one came from.
369///
370/// Returns one [`KeySource`] per entry in `config.llm`, positionally - including
371/// the disabled ones, so the position in the returned slice is the position in the
372/// file. No production caller reads it: `check` discards it, and `doctor` calls
373/// [`source_of`] against the raw TOML tree instead, because `config::load` fails
374/// on an unset `${VAR}` and that is exactly the config `doctor` is most useful on.
375/// It is retained for the tests, which assert the precedence rule per entry
376/// against the one function that decides it, and the positional shape is what lets
377/// them name an entry by the line the user wrote.
378///
379/// **Disabled entries are skipped**, matching every other pass over the provider
380/// list: `${VAR}` expansion and field validation already leave a parked entry
381/// alone, and looking a key up for one would report a missing credential for a
382/// provider that is never contacted. For an `api_key_command` that also means no
383/// subprocess: some helpers are rate-limited and some prompt for a fingerprint,
384/// so spending a real credential call on a provider drep will not contact is
385/// worse than the missing-key report it avoids.
386///
387/// This is the one pass where a credential command runs, so each entry's command
388/// runs exactly once per process however many files the run reviews. A
389/// short-lived credential re-minted per file would fail per file, which the
390/// chain's demotion logic reads as an endpoint problem. There is deliberately no
391/// disk cache and no TTL behind that: drep is a short-lived process, so a
392/// credential written to disk buys nothing and adds a file worth stealing.
393///
394/// Once per process for every *enabled* entry, whether or not the chain reaches
395/// it. Deferring to first use would put credential resolution inside the request
396/// path, and "a broken credential is fatal rather than a provider drep quietly
397/// asks instead" holds precisely because resolution happens before the chain
398/// exists. An unset `${VAR}` in the same position is equally fatal, one layer up,
399/// in `ConfigError::EnvVarUnset`. `enabled = false` is the control for a fallback
400/// whose helper should not be spent.
401pub async fn resolve(config: &mut Config, store: &AuthStore) -> Result<Vec<KeySource>, AuthError> {
402    let mut sources = Vec::with_capacity(config.llm.len());
403    for (index, llm) in config.llm.iter_mut().enumerate() {
404        let source = source_of(
405            Declared {
406                api_key: llm.api_key.as_deref(),
407                has_api_key_command: llm.api_key_command.is_some(),
408                endpoint: llm.endpoint.as_deref(),
409                enabled: llm.enabled,
410            },
411            store,
412        );
413        match source {
414            // `source_of` returns `Command` only when the argv is present, so
415            // the default here is unreachable through it; `command::run` reports
416            // an empty argv rather than panicking if it ever becomes reachable.
417            KeySource::Command => {
418                let argv = llm.api_key_command.as_deref().unwrap_or_default();
419                let key = command::run_bounded(argv)
420                    .await
421                    .map_err(|cause| AuthError::KeyCommand { index, cause })?;
422                llm.api_key = Some(key);
423            }
424            KeySource::Store => {
425                if let Some(endpoint) = llm.endpoint.as_deref()
426                    && let Some(key) = store.get(endpoint)
427                {
428                    llm.api_key = Some(key.to_string());
429                }
430            }
431            KeySource::Config | KeySource::Missing => {}
432        }
433        sources.push(source);
434    }
435    Ok(sources)
436}
437
438/// Run one entry's `api_key_command` and discard the credential.
439///
440/// For `doctor`, whose contract is "what will actually run here": it has to
441/// really invoke the helper, because a helper that no longer authenticates is
442/// precisely what `api_key_command` exists to make visible. Returning `()`
443/// rather than the key is what makes printing it impossible at the call site,
444/// instead of a rule the reporting code has to remember.
445pub async fn probe_key_command(argv: &[String]) -> Result<(), KeyCommandError> {
446    command::run_bounded(argv).await.map(drop)
447}
448
449/// What one `[[llm]]` entry declares about its own credential.
450///
451/// Named fields rather than positional arguments, following `ExplicitFields`:
452/// `check` fills these from a loaded `Config` and `doctor` from the raw TOML
453/// tree, and two `Option<&str>` plus two `bool` in a call is a swap waiting to
454/// happen that the compiler would not catch.
455pub struct Declared<'a> {
456    pub api_key: Option<&'a str>,
457    pub has_api_key_command: bool,
458    pub endpoint: Option<&'a str>,
459    pub enabled: bool,
460}
461
462/// Where a provider's key will come from, given what its config names.
463///
464/// The precedence rule itself, in one place. [`resolve`] applies it to a loaded
465/// `Config`; `doctor` applies it to the *raw* TOML tree, which it has to read
466/// separately so a `${VAR}` prints as itself rather than being swallowed by the
467/// variable-not-set error. Two readers of one rule is the shape
468/// `config::env_var_refs_in` already exists to prevent: doctor once carried a
469/// narrower copy of that scanner and reported a config as fine that `check`
470/// refused to load.
471pub fn source_of(declared: Declared<'_>, store: &AuthStore) -> KeySource {
472    if !declared.enabled {
473        return KeySource::Missing;
474    }
475    if declared.api_key.is_some() {
476        return KeySource::Config;
477    }
478    if declared.has_api_key_command {
479        return KeySource::Command;
480    }
481    match declared.endpoint {
482        Some(endpoint) if store.get(endpoint).is_some() => KeySource::Store,
483        _ => KeySource::Missing,
484    }
485}
486
487#[cfg(test)]
488mod tests;