Skip to main content

graphrt_llm/credentials/
broker.rs

1//! Short-lived credentials from a token broker (your backend).
2//!
3//! ## Contract
4//!
5//! Request: `POST {url}` with JSON `{"provider": "<name>", ...claims}` and the
6//! configured headers plus, when an app credential source is set,
7//! `Authorization: Bearer <app token>` (e.g. the signed-in user's session token).
8//!
9//! Response (2xx, JSON, at most 64 KiB):
10//!
11//! ```json
12//! {
13//!   "token": "short-lived-secret",          // or "access_token"
14//!   "expires_in": 900,                       // seconds (alias "expiresIn")
15//!   "headers": { "x-tenant": "acme" },       // optional, sent with model requests
16//!   "base_url": "https://proxy.example.com/v1" // optional endpoint override
17//! }
18//! ```
19//!
20//! Expiry may instead be given as `expires_at` / `expiresAt` (Unix time; values
21//! above 10^11 are read as milliseconds, smaller ones as seconds) or
22//! `expires_at_ms` / `expiresAtMs` (Unix milliseconds). A response without a usable
23//! expiry is cached for [`TokenBrokerConfig::default_ttl`] (5 minutes), never
24//! indefinitely.
25//!
26//! The broker URL and any returned `base_url` must be `https://` (plain http only
27//! for localhost / 127.0.0.1 / 10.0.2.2 during development): an on-path attacker
28//! must not be able to redirect prompts and keys.
29//!
30//! A 401/403 from the broker maps to [`LlmError::Auth`] (the user must sign in
31//! again); other failures map like provider errors. Use
32//! [`TokenBroker::cached`] so tokens are reused until shortly before expiry.
33
34use std::fmt;
35use std::sync::Arc;
36use std::time::Duration;
37
38use futures::StreamExt;
39use futures::future::BoxFuture;
40use serde::Deserialize;
41
42use super::{CachedCredentials, Credential, CredentialSource, unix_now_ms};
43use crate::error::LlmError;
44
45/// Largest broker response accepted.
46const MAX_RESPONSE_BYTES: usize = 64 * 1024;
47
48/// How the app authenticates to the broker.
49#[derive(Clone, Default)]
50#[non_exhaustive]
51pub enum BrokerAuth {
52    /// No app authentication (only for brokers behind other protection).
53    #[default]
54    None,
55    /// `Authorization: Bearer <secret>` where the secret comes from this source,
56    /// asked with provider name `"token_broker"` (e.g. the user's session token).
57    Bearer(Arc<dyn CredentialSource>),
58}
59
60impl fmt::Debug for BrokerAuth {
61    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62        match self {
63            BrokerAuth::None => f.write_str("None"),
64            BrokerAuth::Bearer(_) => f.write_str("Bearer(<source>)"),
65        }
66    }
67}
68
69/// Token broker settings.
70#[derive(Clone)]
71pub struct TokenBrokerConfig {
72    pub url: String,
73    /// Extra headers sent to the broker.
74    pub headers: Vec<(String, String)>,
75    /// Extra JSON fields sent with every request (e.g. app id, device id).
76    pub claims: serde_json::Map<String, serde_json::Value>,
77    pub auth: BrokerAuth,
78    pub timeout: Duration,
79    /// Lifetime assumed for tokens returned without an expiry.
80    pub default_ttl: Duration,
81}
82
83/// Lifetime assumed for broker tokens that carry no expiry (5 minutes).
84pub const DEFAULT_BROKER_TTL: Duration = Duration::from_secs(300);
85
86impl TokenBrokerConfig {
87    pub fn new(url: impl Into<String>) -> Self {
88        Self {
89            url: url.into(),
90            headers: Vec::new(),
91            claims: serde_json::Map::new(),
92            auth: BrokerAuth::None,
93            timeout: Duration::from_secs(15),
94            default_ttl: DEFAULT_BROKER_TTL,
95        }
96    }
97
98    /// Lifetime assumed for tokens returned without an expiry.
99    pub fn default_ttl(mut self, ttl: Duration) -> Self {
100        self.default_ttl = ttl;
101        self
102    }
103
104    pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
105        self.headers.push((name.into(), value.into()));
106        self
107    }
108
109    pub fn claim(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
110        self.claims.insert(key.into(), value);
111        self
112    }
113
114    pub fn auth(mut self, auth: BrokerAuth) -> Self {
115        self.auth = auth;
116        self
117    }
118}
119
120impl fmt::Debug for TokenBrokerConfig {
121    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
122        f.debug_struct("TokenBrokerConfig")
123            .field("url", &self.url)
124            .field("headers", &self.headers.iter().map(|(k, _)| k).collect::<Vec<_>>())
125            .field("claims", &self.claims.keys().collect::<Vec<_>>())
126            .field("auth", &self.auth)
127            .finish()
128    }
129}
130
131/// Fetches short-lived provider credentials from a broker endpoint.
132#[derive(Clone)]
133pub struct TokenBroker {
134    config: TokenBrokerConfig,
135    client: crate::http::LazyClient,
136}
137
138impl fmt::Debug for TokenBroker {
139    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
140        f.debug_struct("TokenBroker").field("config", &self.config).finish_non_exhaustive()
141    }
142}
143
144#[derive(Deserialize)]
145struct BrokerResponse {
146    #[serde(alias = "access_token")]
147    token: String,
148    #[serde(default, alias = "expiresIn")]
149    expires_in: Option<f64>,
150    #[serde(default, alias = "expiresAt")]
151    expires_at: Option<f64>,
152    #[serde(default, alias = "expiresAtMs")]
153    expires_at_ms: Option<u64>,
154    #[serde(default)]
155    headers: indexmap::IndexMap<String, String>,
156    #[serde(default)]
157    base_url: Option<String>,
158}
159
160impl TokenBroker {
161    pub fn new(config: TokenBrokerConfig) -> Result<Self, LlmError> {
162        crate::credentials::require_secure_endpoint(&config.url, "token broker url")?;
163        let client = crate::http::LazyClient::new(Duration::from_secs(10));
164        Ok(Self { config, client })
165    }
166
167    /// A broker wrapped in [`CachedCredentials`] (the recommended form).
168    pub fn cached(config: TokenBrokerConfig) -> Result<CachedCredentials<Self>, LlmError> {
169        Ok(CachedCredentials::new(Self::new(config)?))
170    }
171
172    async fn fetch(&self, provider: &str) -> Result<Credential, LlmError> {
173        let mut body = self.config.claims.clone();
174        body.insert("provider".into(), serde_json::Value::String(provider.to_owned()));
175        let mut request = self.client.get()?.post(&self.config.url).timeout(self.config.timeout).json(&body);
176        for (k, v) in &self.config.headers {
177            request = request.header(k.as_str(), v.as_str());
178        }
179        if let BrokerAuth::Bearer(source) = &self.config.auth {
180            let app = source.credential("token_broker").await?;
181            request = request.bearer_auth(app.secret);
182        }
183        let response =
184            request.send().await.map_err(|e| LlmError::Network(format!("token broker: {}", e.without_url())))?;
185        let status = response.status().as_u16();
186        let text = read_capped(response).await?;
187        if !(200..300).contains(&status) {
188            if status == 401 || status == 403 {
189                if let BrokerAuth::Bearer(source) = &self.config.auth {
190                    source.invalidate("token_broker");
191                }
192                return Err(LlmError::Auth(format!("token broker rejected the app credential (HTTP {status})")));
193            }
194            return Err(LlmError::from_status(status, &text, None));
195        }
196        let parsed: BrokerResponse =
197            serde_json::from_str(&text).map_err(|e| LlmError::Decode(format!("token broker response: {e}")))?;
198        if parsed.token.is_empty() {
199            return Err(LlmError::Decode("token broker returned an empty token".into()));
200        }
201        let mut credential = Credential::new(parsed.token);
202        let now = unix_now_ms();
203        let expires = expiry_ms(parsed.expires_at_ms, parsed.expires_at, parsed.expires_in, now).unwrap_or_else(|| {
204            now.saturating_add(u64::try_from(self.config.default_ttl.as_millis()).unwrap_or(u64::MAX))
205        });
206        credential = credential.expires_at(expires);
207        for (k, v) in parsed.headers {
208            credential = credential.header(k, v);
209        }
210        if let Some(url) = parsed.base_url.filter(|u| !u.is_empty()) {
211            if !crate::credentials::is_secure_endpoint(&url) {
212                return Err(LlmError::Decode("token broker returned a base_url that is not https".into()));
213            }
214            credential = credential.base_url(url);
215        }
216        Ok(credential)
217    }
218}
219
220/// Unix milliseconds above this are treated as milliseconds in `expires_at`
221/// (10^11 seconds is the year 5138; 10^11 milliseconds is 1973).
222const MS_THRESHOLD: f64 = 1e11;
223
224/// The absolute expiry from the response fields, or `None` when none is usable.
225fn expiry_ms(at_ms: Option<u64>, at: Option<f64>, in_secs: Option<f64>, now: u64) -> Option<u64> {
226    if let Some(ms) = at_ms.filter(|ms| *ms > 0) {
227        return Some(ms);
228    }
229    if let Some(at) = at.filter(|v| v.is_finite() && *v > 0.0) {
230        return Some(if at > MS_THRESHOLD { secs_to_ms(at / 1000.0) } else { secs_to_ms(at) });
231    }
232    in_secs.filter(|s| s.is_finite() && *s >= 0.0).map(|s| now.saturating_add(secs_to_ms(s)))
233}
234
235fn secs_to_ms(secs: f64) -> u64 {
236    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
237    let ms = (secs * 1000.0).min(u64::MAX as f64) as u64;
238    ms
239}
240
241async fn read_capped(response: reqwest::Response) -> Result<String, LlmError> {
242    let mut bytes = Vec::new();
243    let mut stream = response.bytes_stream();
244    while let Some(chunk) = stream.next().await {
245        let chunk = chunk.map_err(|e| LlmError::Network(format!("token broker: {}", e.without_url())))?;
246        if bytes.len().saturating_add(chunk.len()) > MAX_RESPONSE_BYTES {
247            return Err(LlmError::Decode("token broker response exceeds 64 KiB".into()));
248        }
249        bytes.extend_from_slice(&chunk);
250    }
251    String::from_utf8(bytes).map_err(|_| LlmError::Decode("token broker response is not UTF-8".into()))
252}
253
254impl CredentialSource for TokenBroker {
255    fn credential<'a>(&'a self, provider: &'a str) -> BoxFuture<'a, Result<Credential, LlmError>> {
256        Box::pin(self.fetch(provider))
257    }
258
259    /// Tokens minted for one app session must not outlive it: when the app
260    /// credential source changes (sign-out, new user), cached tokens are dropped.
261    fn generation(&self) -> u64 {
262        match &self.config.auth {
263            BrokerAuth::Bearer(source) => source.generation(),
264            BrokerAuth::None => 0,
265        }
266    }
267}
268
269#[cfg(test)]
270mod tests {
271    use super::*;
272
273    #[test]
274    fn expiry_parsing() {
275        let now = 1_700_000_000_000;
276        assert_eq!(expiry_ms(Some(5), None, None, now), Some(5));
277        // Seconds vs milliseconds in `expires_at`.
278        assert_eq!(expiry_ms(None, Some(1_700_000_900.0), None, now), Some(1_700_000_900_000));
279        assert_eq!(expiry_ms(None, Some(1_700_000_900_000.0), None, now), Some(1_700_000_900_000));
280        assert_eq!(expiry_ms(None, None, Some(60.0), now), Some(now + 60_000));
281        // Unusable values yield no expiry (the caller applies the default TTL).
282        assert_eq!(expiry_ms(None, Some(f64::NAN), Some(-1.0), now), None);
283        assert_eq!(expiry_ms(Some(0), Some(0.0), None, now), None);
284    }
285
286    #[test]
287    fn camel_case_fields_and_insecure_urls() {
288        let parsed: BrokerResponse = serde_json::from_str(r#"{"token":"t","expiresIn":30}"#).unwrap();
289        assert_eq!(parsed.expires_in, Some(30.0));
290        assert!(TokenBroker::new(TokenBrokerConfig::new("http://broker.example.com/token")).is_err());
291        assert!(TokenBroker::new(TokenBrokerConfig::new("http://127.0.0.1:9/token")).is_ok());
292        assert!(TokenBroker::new(TokenBrokerConfig::new("https://broker.example.com/token")).is_ok());
293    }
294}