Skip to main content

auth_framework/server/oauth/
par.rs

1//! Pushed Authorization Requests (PAR) Implementation - RFC 9126
2//!
3//! This module implements RFC 9126 - OAuth 2.0 Pushed Authorization Requests
4/// which enhances security by allowing clients to push authorization request
5/// parameters directly to the authorization server.
6use crate::errors::{AuthError, Result};
7use crate::storage::AuthStorage;
8use serde::{Deserialize, Serialize};
9use std::collections::HashMap;
10use std::sync::Arc;
11use std::time::{Duration, SystemTime};
12use uuid::Uuid;
13
14/// PAR request containing authorization parameters
15#[derive(Debug, Clone, Serialize, Deserialize)]
16pub struct PushedAuthorizationRequest {
17    /// Client identifier
18    pub client_id: String,
19
20    /// Response type (e.g., "code")
21    pub response_type: String,
22
23    /// Redirect URI
24    pub redirect_uri: String,
25
26    /// Requested scopes
27    pub scope: Option<String>,
28
29    /// State parameter
30    pub state: Option<String>,
31
32    /// PKCE code challenge
33    pub code_challenge: Option<String>,
34
35    /// PKCE code challenge method
36    pub code_challenge_method: Option<String>,
37
38    /// Additional parameters
39    #[serde(flatten)]
40    pub additional_params: HashMap<String, String>,
41}
42
43/// PAR response containing request URI
44#[derive(Clone, Serialize, Deserialize)]
45pub struct PushedAuthorizationResponse {
46    /// Request URI to be used in subsequent authorization request
47    pub request_uri: String,
48
49    /// Expiration time in seconds
50    pub expires_in: u64,
51}
52
53impl std::fmt::Debug for PushedAuthorizationResponse {
54    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
55        let mut d = f.debug_struct("PushedAuthorizationResponse");
56        d.field(
57            "request_uri",
58            &crate::utils::redact::redacted(&self.request_uri),
59        );
60        d.field("expires_in", &self.expires_in);
61        d.finish()
62    }
63}
64
65/// Stored PAR request with metadata
66#[derive(Debug, Clone, Serialize, Deserialize)]
67pub struct StoredPushedRequest {
68    /// Original request parameters
69    pub request: PushedAuthorizationRequest,
70
71    /// When the request was created
72    pub created_at: SystemTime,
73
74    /// When the request expires
75    pub expires_at: SystemTime,
76
77    /// Whether the request has been used
78    pub used: bool,
79}
80
81/// PAR request manager with persistent storage
82use std::fmt;
83
84#[derive(Clone)]
85pub struct PARManager {
86    /// Persistent storage backend
87    storage: Arc<dyn AuthStorage>,
88
89    /// Memory cache for fast access
90    requests: Arc<tokio::sync::RwLock<HashMap<String, StoredPushedRequest>>>,
91
92    /// Default expiration time for PAR requests
93    default_expiration: Duration,
94}
95
96impl fmt::Debug for PARManager {
97    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
98        f.debug_struct("PARManager")
99            .field("storage", &"<dyn AuthStorage>")
100            .field("default_expiration", &self.default_expiration)
101            .finish()
102    }
103}
104
105impl PARManager {
106    /// Create a new PAR manager with storage backend
107    pub fn new(storage: Arc<dyn AuthStorage>) -> Self {
108        Self {
109            storage,
110            requests: Arc::new(tokio::sync::RwLock::new(HashMap::new())),
111            default_expiration: Duration::from_secs(90), // RFC 9126 recommendation
112        }
113    }
114
115    /// Create a new PAR manager with custom expiration
116    pub fn with_expiration(storage: Arc<dyn AuthStorage>, expiration: Duration) -> Self {
117        Self {
118            storage,
119            requests: Arc::new(tokio::sync::RwLock::new(HashMap::new())),
120            default_expiration: expiration,
121        }
122    }
123
124    /// Store a pushed authorization request
125    pub async fn store_request(
126        &self,
127        request: PushedAuthorizationRequest,
128    ) -> Result<PushedAuthorizationResponse> {
129        // Validate the request
130        self.validate_request(&request)?;
131
132        // Generate request URI
133        let request_id = Uuid::new_v4().to_string();
134        let request_uri = format!("urn:ietf:params:oauth:request_uri:{}", request_id);
135
136        // Calculate expiration
137        let now = SystemTime::now();
138        let expires_at = now + self.default_expiration;
139
140        // Store the request in persistent storage with TTL
141        let stored_request = StoredPushedRequest {
142            request: request.clone(),
143            created_at: now,
144            expires_at,
145            used: false,
146        };
147
148        // Store in persistent backend with TTL
149        let storage_key = format!("par:{}", request_uri);
150        let serialized = serde_json::to_string(&stored_request)
151            .map_err(|e| AuthError::internal(format!("Failed to serialize PAR request: {}", e)))?;
152
153        self.storage
154            .store_kv(
155                &storage_key,
156                &serialized.into_bytes(),
157                Some(self.default_expiration),
158            )
159            .await
160            .map_err(|e| AuthError::internal(format!("Failed to store PAR request: {}", e)))?;
161
162        // Also cache in memory for fast access
163        let mut requests = self.requests.write().await;
164        requests.insert(request_uri.clone(), stored_request);
165
166        // Clean up expired requests from memory cache
167        self.cleanup_expired_requests(&mut requests, now);
168
169        Ok(PushedAuthorizationResponse {
170            request_uri,
171            expires_in: self.default_expiration.as_secs(),
172        })
173    }
174
175    /// Retrieve and consume a pushed authorization request
176    pub async fn consume_request(&self, request_uri: &str) -> Result<PushedAuthorizationRequest> {
177        let storage_key = format!("par:{}", request_uri);
178
179        // Try to load from persistent storage first
180        let stored_request = if let Some(data) = self.storage.get_kv(&storage_key).await? {
181            let serialized = String::from_utf8(data)
182                .map_err(|_| AuthError::internal("Invalid UTF-8 in stored PAR data"))?;
183
184            serde_json::from_str::<StoredPushedRequest>(&serialized).map_err(|e| {
185                AuthError::internal(format!("Failed to deserialize PAR request: {}", e))
186            })?
187        } else {
188            // Fallback to memory cache (for backward compatibility during transition)
189            let requests = self.requests.read().await;
190            requests
191                .get(request_uri)
192                .cloned()
193                .ok_or_else(|| AuthError::auth_method("par", "Invalid request_uri"))?
194        };
195
196        // Check if expired
197        let now = SystemTime::now();
198        if now > stored_request.expires_at {
199            // Clean up from both storage and cache
200            let _ = self.storage.delete_kv(&storage_key).await;
201            let mut requests = self.requests.write().await;
202            requests.remove(request_uri);
203            return Err(AuthError::auth_method("par", "Request URI expired"));
204        }
205
206        // Check if already used
207        if stored_request.used {
208            return Err(AuthError::auth_method("par", "Request URI already used"));
209        }
210
211        // Mark as consumed by removing from storage (single use)
212        self.storage
213            .delete_kv(&storage_key)
214            .await
215            .map_err(|e| AuthError::internal(format!("Failed to consume PAR request: {}", e)))?;
216
217        // Also remove from memory cache
218        let mut requests = self.requests.write().await;
219        requests.remove(request_uri);
220
221        Ok(stored_request.request)
222    }
223
224    /// Validate a PAR request
225    fn validate_request(&self, request: &PushedAuthorizationRequest) -> Result<()> {
226        // Validate required parameters
227        if request.client_id.is_empty() {
228            return Err(AuthError::auth_method("par", "Missing client_id"));
229        }
230
231        if request.response_type.is_empty() {
232            return Err(AuthError::auth_method("par", "Missing response_type"));
233        }
234
235        if request.redirect_uri.is_empty() {
236            return Err(AuthError::auth_method("par", "Missing redirect_uri"));
237        }
238
239        // Validate redirect URI format
240        if url::Url::parse(&request.redirect_uri).is_err() {
241            return Err(AuthError::auth_method("par", "Invalid redirect_uri format"));
242        }
243
244        // Validate PKCE parameters if present
245        if let (Some(challenge), Some(method)) =
246            (&request.code_challenge, &request.code_challenge_method)
247        {
248            if method != "S256" && method != "plain" {
249                return Err(AuthError::auth_method(
250                    "par",
251                    "Invalid code_challenge_method",
252                ));
253            }
254
255            if challenge.is_empty() {
256                return Err(AuthError::auth_method("par", "Empty code_challenge"));
257            }
258        }
259
260        Ok(())
261    }
262
263    /// Clean up expired requests
264    fn cleanup_expired_requests(
265        &self,
266        requests: &mut HashMap<String, StoredPushedRequest>,
267        now: SystemTime,
268    ) {
269        requests.retain(|_, stored_request| now <= stored_request.expires_at);
270    }
271
272    /// Get statistics about stored requests
273    pub async fn get_statistics(&self) -> PARStatistics {
274        let requests = self.requests.read().await;
275        let now = SystemTime::now();
276
277        let total_count = requests.len();
278        let expired_count = requests.values().filter(|req| now > req.expires_at).count();
279        let used_count = requests.values().filter(|req| req.used).count();
280
281        PARStatistics {
282            total_requests: total_count,
283            expired_requests: expired_count,
284            used_requests: used_count,
285            active_requests: total_count - expired_count - used_count,
286        }
287    }
288}
289
290/// PAR statistics
291#[derive(Debug, Clone, Serialize, Deserialize)]
292pub struct PARStatistics {
293    /// Total number of stored requests
294    pub total_requests: usize,
295
296    /// Number of expired requests
297    pub expired_requests: usize,
298
299    /// Number of used requests
300    pub used_requests: usize,
301
302    /// Number of active (valid, unused) requests
303    pub active_requests: usize,
304}
305
306#[cfg(test)]
307mod tests {
308    use super::*;
309    use tokio::time::sleep;
310
311    fn create_test_request() -> PushedAuthorizationRequest {
312        PushedAuthorizationRequest {
313            client_id: "test_client".to_string(),
314            response_type: "code".to_string(),
315            redirect_uri: "https://example.com/callback".to_string(),
316            scope: Some("openid profile".to_string()),
317            state: Some("test_state".to_string()),
318            code_challenge: Some("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk".to_string()),
319            code_challenge_method: Some("S256".to_string()),
320            additional_params: HashMap::new(),
321        }
322    }
323
324    #[tokio::test]
325    async fn test_store_and_consume_request() {
326        use crate::storage::MemoryStorage;
327        use std::sync::Arc;
328
329        let storage = Arc::new(MemoryStorage::new());
330        let par_manager = PARManager::new(storage);
331        let request = create_test_request();
332
333        // Store the request
334        let response = par_manager.store_request(request.clone()).await.unwrap();
335        assert!(
336            response
337                .request_uri
338                .starts_with("urn:ietf:params:oauth:request_uri:")
339        );
340        assert_eq!(response.expires_in, 90);
341
342        // Consume the request
343        let consumed_request = par_manager
344            .consume_request(&response.request_uri)
345            .await
346            .unwrap();
347        assert_eq!(consumed_request.client_id, request.client_id);
348        assert_eq!(consumed_request.response_type, request.response_type);
349
350        // Try to consume again (should fail)
351        let result = par_manager.consume_request(&response.request_uri).await;
352        assert!(result.is_err());
353    }
354
355    #[tokio::test]
356    async fn test_request_expiration() {
357        use crate::storage::MemoryStorage;
358        use std::sync::Arc;
359
360        let storage = Arc::new(MemoryStorage::new());
361        let par_manager = PARManager::with_expiration(storage, Duration::from_millis(50));
362        let request = create_test_request();
363
364        // Store the request
365        let response = par_manager.store_request(request).await.unwrap();
366
367        // Wait for expiration
368        sleep(Duration::from_millis(100)).await;
369
370        // Try to consume (should fail due to expiration)
371        let result = par_manager.consume_request(&response.request_uri).await;
372        assert!(result.is_err());
373    }
374
375    #[tokio::test]
376    async fn test_invalid_request_validation() {
377        use crate::storage::MemoryStorage;
378        use std::sync::Arc;
379
380        let storage = Arc::new(MemoryStorage::new());
381        let par_manager = PARManager::new(storage);
382
383        // Test missing client_id
384        let mut request = create_test_request();
385        request.client_id = "".to_string();
386        let result = par_manager.store_request(request).await;
387        assert!(result.is_err());
388
389        // Test invalid redirect_uri
390        let mut request = create_test_request();
391        request.redirect_uri = "invalid-uri".to_string();
392        let result = par_manager.store_request(request).await;
393        assert!(result.is_err());
394
395        // Test invalid PKCE method
396        let mut request = create_test_request();
397        request.code_challenge_method = Some("invalid".to_string());
398        let result = par_manager.store_request(request).await;
399        assert!(result.is_err());
400    }
401
402    #[tokio::test]
403    async fn test_statistics() {
404        use crate::storage::MemoryStorage;
405        use std::sync::Arc;
406
407        let storage = Arc::new(MemoryStorage::new());
408        let par_manager = PARManager::new(storage);
409        let request = create_test_request();
410
411        // Initial statistics
412        let stats = par_manager.get_statistics().await;
413        assert_eq!(stats.total_requests, 0);
414
415        // Store a request
416        let response = par_manager.store_request(request).await.unwrap();
417        let stats = par_manager.get_statistics().await;
418        assert_eq!(stats.total_requests, 1);
419        assert_eq!(stats.active_requests, 1);
420
421        // Consume the request
422        par_manager
423            .consume_request(&response.request_uri)
424            .await
425            .unwrap();
426        let stats = par_manager.get_statistics().await;
427        assert_eq!(stats.total_requests, 0); // Removed after consumption
428    }
429}