1use core::fmt;
4use std::collections::HashMap;
5use std::sync::{Arc, PoisonError, RwLock};
6use std::time::{Duration, Instant};
7
8use serde::Deserialize;
9use serde_json::Value;
10use url::Url;
11
12use super::{KeyReference, KeyResolutionError, KeyResolver, KeyRole};
13use crate::jose::Jwk;
14use crate::methods::web::{HttpClient, HttpError, fetchable};
15
16pub struct JwksResolver<C> {
71 client: C,
72 ttl: Duration,
73 capacity: usize,
74 cache: RwLock<HashMap<Url, Entry>>,
75}
76
77struct Entry {
79 keys: Arc<[Value]>,
80 expires_at: Option<Instant>,
81}
82
83impl Entry {
84 fn is_live(&self, now: Instant) -> bool {
85 self.expires_at.is_none_or(|expires_at| expires_at > now)
86 }
87}
88
89#[derive(Deserialize)]
91struct Metadata {
92 issuer: String,
93 #[serde(default)]
94 jwks: Option<KeySet>,
95 #[serde(default)]
96 jwks_uri: Option<String>,
97}
98
99#[derive(Deserialize)]
102struct KeySet {
103 keys: Vec<Value>,
104}
105
106impl<C> JwksResolver<C> {
107 pub const DEFAULT_TTL: Duration = Duration::from_mins(5);
109
110 pub const DEFAULT_CAPACITY: usize = 256;
112
113 pub fn new(client: C) -> Self {
116 Self {
117 client,
118 ttl: Self::DEFAULT_TTL,
119 capacity: Self::DEFAULT_CAPACITY,
120 cache: RwLock::new(HashMap::new()),
121 }
122 }
123
124 #[must_use]
126 pub fn with_ttl(mut self, ttl: Duration) -> Self {
127 self.ttl = ttl;
128 self
129 }
130
131 #[must_use]
133 pub fn with_capacity(mut self, capacity: usize) -> Self {
134 self.capacity = capacity.max(1);
135 self
136 }
137
138 pub fn ttl(&self) -> Duration {
140 self.ttl
141 }
142
143 pub fn client(&self) -> &C {
145 &self.client
146 }
147
148 fn cached(&self, issuer: &Url) -> Option<Arc<[Value]>> {
150 let cache = self.cache.read().unwrap_or_else(PoisonError::into_inner);
151 cache
152 .get(issuer)
153 .filter(|entry| entry.is_live(Instant::now()))
154 .map(|entry| Arc::clone(&entry.keys))
155 }
156
157 fn store(&self, issuer: &Url, keys: Arc<[Value]>) {
160 if self.ttl.is_zero() {
161 return;
162 }
163 let now = Instant::now();
164 let mut cache = self.cache.write().unwrap_or_else(PoisonError::into_inner);
165 if !cache.contains_key(issuer) && cache.len() >= self.capacity {
166 cache.retain(|_, entry| entry.is_live(now));
167 if cache.len() >= self.capacity
168 && let Some(soonest) = cache
169 .iter()
170 .min_by_key(|(_, entry)| entry.expires_at)
171 .map(|(issuer, _)| issuer.clone())
172 {
173 cache.remove(&soonest);
174 }
175 }
176 cache.insert(
177 issuer.clone(),
178 Entry {
179 keys,
180 expires_at: now.checked_add(self.ttl),
181 },
182 );
183 }
184}
185
186impl<C: HttpClient> JwksResolver<C> {
187 async fn key_set(&self, issuer: &Url) -> Result<Arc<[Value]>, JwksError> {
189 if let Some(keys) = self.cached(issuer) {
190 return Ok(keys);
191 }
192 let url = metadata_url(issuer)?;
193 if !fetchable(&self.client, &url) {
194 return Err(JwksError::NotHttps(issuer.clone()));
195 }
196 let metadata: Metadata = self.fetch_json(&url).await?;
197 if Url::parse(&metadata.issuer).ok().as_ref() != Some(issuer) {
198 return Err(JwksError::IssuerMismatch {
199 expected: issuer.clone(),
200 found: metadata.issuer,
201 });
202 }
203 let keys = match (metadata.jwks, metadata.jwks_uri) {
204 (Some(jwks), None) => jwks.keys,
205 (None, Some(jwks_uri)) => {
206 let jwks_uri = Url::parse(&jwks_uri).map_err(|e| JwksError::InvalidMetadata {
207 url: url.clone(),
208 reason: format!("`jwks_uri` {jwks_uri:?}: {e}"),
209 })?;
210 if !fetchable(&self.client, &jwks_uri) {
211 return Err(JwksError::NotHttps(jwks_uri));
212 }
213 self.fetch_json::<KeySet>(&jwks_uri).await?.keys
214 }
215 (Some(_), Some(_)) => {
216 return Err(JwksError::InvalidMetadata {
217 url,
218 reason: "both `jwks` and `jwks_uri` are present".to_owned(),
219 });
220 }
221 (None, None) => {
222 return Err(JwksError::InvalidMetadata {
223 url,
224 reason: "neither `jwks` nor `jwks_uri` is present".to_owned(),
225 });
226 }
227 };
228 let keys: Arc<[Value]> = keys.into();
229 self.store(issuer, Arc::clone(&keys));
230 Ok(keys)
231 }
232
233 async fn fetch_json<T: serde::de::DeserializeOwned>(&self, url: &Url) -> Result<T, JwksError> {
235 let response = self
236 .client
237 .get(url)
238 .await
239 .map_err(|source| JwksError::Http {
240 url: url.clone(),
241 source,
242 })?;
243 if !(200..300).contains(&response.status) {
244 return Err(JwksError::HttpStatus {
245 url: url.clone(),
246 status: response.status,
247 });
248 }
249 serde_json::from_slice(&response.body).map_err(|e| JwksError::InvalidMetadata {
250 url: url.clone(),
251 reason: e.to_string(),
252 })
253 }
254}
255
256fn metadata_url(issuer: &Url) -> Result<Url, JwksError> {
259 if issuer.query().is_some()
260 || issuer.fragment().is_some()
261 || issuer.host().is_none()
262 || !issuer.username().is_empty()
263 || issuer.password().is_some()
264 {
265 return Err(JwksError::InvalidIssuer(issuer.clone()));
266 }
267 let path = issuer.path().trim_end_matches('/');
268 let mut url = issuer.clone();
269 url.set_path(&format!("/.well-known/jwt-vc-issuer{path}"));
270 Ok(url)
271}
272
273fn select(keys: &[Value], issuer: &Url, kid: &str) -> Result<Jwk, JwksError> {
275 let mut matching = keys
276 .iter()
277 .filter(|key| key.get("kid").and_then(Value::as_str) == Some(kid));
278 let key = matching.next().ok_or_else(|| JwksError::UnknownKid {
279 issuer: issuer.clone(),
280 kid: kid.to_owned(),
281 })?;
282 if matching.next().is_some() {
283 return Err(JwksError::DuplicateKid {
284 issuer: issuer.clone(),
285 kid: kid.to_owned(),
286 });
287 }
288 let jwk: Jwk = serde_json::from_value(key.clone()).map_err(|e| JwksError::InvalidKey {
289 kid: kid.to_owned(),
290 reason: e.to_string(),
291 })?;
292 if jwk.is_private() {
293 return Err(JwksError::InvalidKey {
294 kid: kid.to_owned(),
295 reason: "the key set publishes private material".to_owned(),
296 });
297 }
298 Ok(jwk)
299}
300
301impl<C> fmt::Debug for JwksResolver<C>
302where
303 C: fmt::Debug,
304{
305 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
306 f.debug_struct("JwksResolver")
307 .field("client", &self.client)
308 .field("ttl", &self.ttl)
309 .field("capacity", &self.capacity)
310 .finish_non_exhaustive()
311 }
312}
313
314#[async_trait::async_trait]
315impl<C: HttpClient> KeyResolver for JwksResolver<C> {
316 async fn resolve_key(&self, key: &KeyReference, _: KeyRole) -> Result<Jwk, KeyResolutionError> {
317 let KeyReference::Jwks { issuer, kid } = key else {
318 return Err(KeyResolutionError::unsupported(key));
319 };
320 let keys = self.key_set(issuer).await?;
321 Ok(select(&keys, issuer, kid)?)
322 }
323}
324
325#[derive(Debug, thiserror::Error)]
327#[non_exhaustive]
328pub enum JwksError {
329 #[error("`{0}` is not an HTTPS URL")]
331 NotHttps(Url),
332 #[error(
334 "`{0}` is not an issuer identifier: it has a query, a fragment or credentials, or no host"
335 )]
336 InvalidIssuer(Url),
337 #[error("fetching `{url}` failed: {source}")]
339 Http {
340 url: Url,
342 #[source]
344 source: HttpError,
345 },
346 #[error("fetching `{url}` returned HTTP {status}")]
348 HttpStatus {
349 url: Url,
351 status: u16,
353 },
354 #[error("`{url}`: {reason}")]
356 InvalidMetadata {
357 url: Url,
359 reason: String,
361 },
362 #[error("the metadata of `{expected}` names the issuer {found:?}")]
364 IssuerMismatch {
365 expected: Url,
367 found: String,
369 },
370 #[error("issuer `{issuer}` has no key `{kid}`")]
372 UnknownKid {
373 issuer: Url,
375 kid: String,
377 },
378 #[error("issuer `{issuer}` has several keys `{kid}`")]
380 DuplicateKid {
381 issuer: Url,
383 kid: String,
385 },
386 #[error("key `{kid}`: {reason}")]
388 InvalidKey {
389 kid: String,
391 reason: String,
393 },
394}
395
396impl From<JwksError> for KeyResolutionError {
397 fn from(error: JwksError) -> Self {
398 Self::new(error)
399 }
400}
401
402#[cfg(test)]
403mod tests {
404 use super::*;
405
406 #[test]
407 fn an_entry_expires_at_its_instant() {
408 let now = Instant::now();
409 let entry = Entry {
410 keys: Arc::from([]),
411 expires_at: Some(now),
412 };
413 assert!(entry.is_live(now.checked_sub(Duration::from_nanos(1)).unwrap()));
414 assert!(!entry.is_live(now));
415 }
416}