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;