Skip to main content

graphrt_llm/
credentials.rs

1//! Dynamic credentials for model providers.
2//!
3//! A static API key is fine on a server, but an app running on a user's device
4//! must not ship a provider key inside its binary. Providers therefore accept a
5//! [`CredentialSource`], asked for a credential right before each request:
6//!
7//! - bring-your-own-key: the host app reads the user's key from the platform
8//!   keychain / keystore;
9//! - token broker: a backend issues short-lived, per-user tokens;
10//! - static keys for servers and tests ([`StaticCredential`]).
11//!
12//! Sources are consulted per request. Wrap slow or rate-limited sources in
13//! [`CachedCredentials`], which caches until shortly before expiry and shares
14//! one refresh between concurrent requests.
15//!
16//! | Source | Use |
17//! | --- | --- |
18//! | [`StaticCredential`] | Servers, tests. |
19//! | [`EnvCredentials`] | Servers: read the key from an environment variable at request time. |
20//! | [`FnCredentials`] | Hosts: any async closure (keychain lookup, custom auth). |
21//! | [`TokenBroker`] (feature `http`) | Apps: short-lived tokens from your backend. |
22//!
23//! See `docs/credentials.md` for the threat model and the proxy pattern.
24
25#[cfg(feature = "http")]
26mod broker;
27mod cached;
28mod sources;
29
30#[cfg(feature = "http")]
31pub use broker::{BrokerAuth, TokenBroker, TokenBrokerConfig};
32pub use cached::{CachedCredentials, DEFAULT_REFRESH_SKEW_MS};
33pub use sources::{EnvCredentials, FnCredentials};
34
35use std::fmt;
36
37use futures::future::BoxFuture;
38
39use crate::error::LlmError;
40
41/// A credential to authenticate one request.
42#[derive(Clone, PartialEq, Eq)]
43pub struct Credential {
44    /// The secret sent to the provider (API key or bearer token).
45    pub secret: String,
46    /// Absolute expiry in Unix milliseconds, when known.
47    pub expires_at_ms: Option<u64>,
48    /// Extra headers to attach (e.g. a tenant or session header issued with a token).
49    pub headers: Vec<(String, String)>,
50    /// Endpoint override issued with the credential (e.g. a regional proxy). Applied
51    /// in place of the provider's configured base URL when set.
52    pub base_url: Option<String>,
53}
54
55impl Credential {
56    pub fn new(secret: impl Into<String>) -> Self {
57        Self { secret: secret.into(), expires_at_ms: None, headers: Vec::new(), base_url: None }
58    }
59
60    pub fn expires_at(mut self, unix_ms: u64) -> Self {
61        self.expires_at_ms = Some(unix_ms);
62        self
63    }
64
65    pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
66        self.headers.push((name.into(), value.into()));
67        self
68    }
69
70    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
71        self.base_url = Some(base_url.into());
72        self
73    }
74
75    /// Whether the credential is expired (or within `skew_ms` of expiring) at `now_ms`.
76    pub fn is_expired_at(&self, now_ms: u64, skew_ms: u64) -> bool {
77        self.expires_at_ms.is_some_and(|exp| now_ms.saturating_add(skew_ms) >= exp)
78    }
79}
80
81/// Current Unix time in milliseconds. On `wasm32-unknown-unknown`, where there is
82/// no system clock, returns 0: credentials then never expire by time and are
83/// refreshed only through [`CredentialSource::invalidate`].
84pub fn unix_now_ms() -> u64 {
85    #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
86    {
87        0
88    }
89    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
90    {
91        std::time::SystemTime::now()
92            .duration_since(std::time::UNIX_EPOCH)
93            .map(|d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX))
94            .unwrap_or(0)
95    }
96}
97
98impl fmt::Debug for Credential {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        f.debug_struct("Credential")
101            .field("secret", &"<redacted>")
102            .field("expires_at_ms", &self.expires_at_ms)
103            .field("headers", &self.headers.iter().map(|(k, _)| k).collect::<Vec<_>>())
104            .field("base_url", &self.base_url)
105            .finish()
106    }
107}
108
109/// Whether `url` may receive credentials: `https://`, or `http://` to a loopback /
110/// Android-emulator-host address (local development and tests only).
111pub fn is_secure_endpoint(url: &str) -> bool {
112    if url.starts_with("https://") {
113        return true;
114    }
115    let Some(rest) = url.strip_prefix("http://") else {
116        return false;
117    };
118    let authority = rest.split(['/', '?', '#']).next().unwrap_or_default();
119    let authority = authority.rsplit_once('@').map_or(authority, |(_, host)| host);
120    let host = match authority.strip_prefix('[') {
121        Some(v6) => v6.split(']').next().unwrap_or_default(),
122        None => authority.rsplit_once(':').map_or(authority, |(h, _)| h),
123    };
124    matches!(host, "localhost" | "::1" | "10.0.2.2")
125        || host.parse::<std::net::Ipv4Addr>().is_ok_and(|ip| ip.is_loopback())
126}
127
128/// Validate an endpoint that will receive credentials.
129pub fn require_secure_endpoint(url: &str, what: &str) -> Result<(), LlmError> {
130    if is_secure_endpoint(url) {
131        Ok(())
132    } else {
133        Err(LlmError::Config(format!(
134            "{what} must use https:// (plain http is only allowed for localhost / 127.0.0.1 / 10.0.2.2)"
135        )))
136    }
137}
138
139/// Supplies credentials on demand.
140pub trait CredentialSource: Send + Sync + fmt::Debug {
141    /// Credential for `provider` (the registry name, e.g. `openai`).
142    fn credential<'a>(&'a self, provider: &'a str) -> BoxFuture<'a, Result<Credential, LlmError>>;
143
144    /// Called when the provider rejected the last credential (HTTP 401/403), so
145    /// cached values can be dropped before one retry.
146    fn invalidate(&self, provider: &str) {
147        let _ = provider;
148    }
149
150    /// A counter that changes whenever credentials this source would return for
151    /// any provider may have changed outside of [`CredentialSource::invalidate`]
152    /// (e.g. the host app signed a user out or registered a new key source).
153    /// [`CachedCredentials`] drops cached values when it changes. Default: never changes.
154    fn generation(&self) -> u64 {
155        0
156    }
157}
158
159/// A fixed secret.
160#[derive(Clone)]
161pub struct StaticCredential(Credential);
162
163impl StaticCredential {
164    pub fn new(secret: impl Into<String>) -> Self {
165        Self(Credential::new(secret))
166    }
167
168    /// A fixed, fully specified credential (headers, base URL, expiry).
169    pub fn from_credential(credential: Credential) -> Self {
170        Self(credential)
171    }
172}
173
174impl fmt::Debug for StaticCredential {
175    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
176        f.write_str("StaticCredential(<redacted>)")
177    }
178}
179
180impl CredentialSource for StaticCredential {
181    fn credential<'a>(&'a self, _provider: &'a str) -> BoxFuture<'a, Result<Credential, LlmError>> {
182        Box::pin(futures::future::ready(Ok(self.0.clone())))
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    #[test]
191    fn debug_never_shows_secrets() {
192        let c = Credential::new("sk-secret").header("x-tenant", "t-secret");
193        let text = format!("{c:?} {:?}", StaticCredential::new("sk-secret"));
194        assert!(!text.contains("sk-secret"));
195        assert!(!text.contains("t-secret"));
196    }
197}