Skip to main content

auth_framework/protocols/
paseto.rs

1//! PASETO (Platform-Agnostic Security Tokens) v4 implementation.
2//!
3//! Provides local (symmetric, encrypted) PASETO v4 token operations
4//! as a secure alternative to JWT.
5
6use crate::errors::{AuthError, Result};
7use pasetors::claims::{Claims, ClaimsValidationRules};
8use pasetors::footer::Footer;
9use pasetors::keys::{Generate, SymmetricKey};
10use pasetors::token::UntrustedToken;
11use pasetors::version4::V4;
12use pasetors::{Local, local};
13use serde::{Deserialize, Serialize};
14use std::collections::HashMap;
15use std::time::Duration;
16
17/// Configuration for PASETO token operations.
18#[derive(Debug, Clone, Serialize, Deserialize)]
19pub struct PasetoConfig {
20    pub issuer: String,
21    pub token_lifetime: Duration,
22    pub audience: Option<String>,
23    pub footer: Option<String>,
24}
25
26impl Default for PasetoConfig {
27    fn default() -> Self {
28        Self {
29            issuer: "auth-framework".to_string(),
30            token_lifetime: Duration::from_secs(3600),
31            audience: None,
32            footer: None,
33        }
34    }
35}
36
37/// Decoded PASETO token payload.
38#[derive(Clone)]
39pub struct PasetoToken {
40    pub subject: String,
41    pub issuer: String,
42    pub token_id: Option<String>,
43    pub audience: Option<String>,
44    pub custom_claims: HashMap<String, String>,
45}
46
47impl std::fmt::Debug for PasetoToken {
48    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
49        let mut d = f.debug_struct("PasetoToken");
50        d.field("subject", &self.subject);
51        d.field("issuer", &self.issuer);
52        d.field("token_id", &crate::utils::redact::redacted(&self.token_id));
53        d.field("audience", &self.audience);
54        d.field("custom_claims", &self.custom_claims);
55        d.finish()
56    }
57}
58
59/// PASETO v4.local token manager (symmetric encryption).
60pub struct PasetoLocalManager {
61    config: PasetoConfig,
62    key: SymmetricKey<V4>,
63}
64
65impl PasetoLocalManager {
66    /// Create a new manager by generating a fresh random key.
67    pub fn new(config: PasetoConfig) -> Result<Self> {
68        let key = SymmetricKey::<V4>::generate()
69            .map_err(|e| AuthError::crypto(format!("Failed to generate PASETO key: {e}")))?;
70        Ok(Self { config, key })
71    }
72
73    /// Create from existing raw 32-byte key material.
74    pub fn from_key_bytes(config: PasetoConfig, key_bytes: &[u8; 32]) -> Result<Self> {
75        let key = SymmetricKey::<V4>::from(key_bytes)
76            .map_err(|e| AuthError::crypto(format!("Invalid PASETO key: {e}")))?;
77        Ok(Self { config, key })
78    }
79
80    /// Issue an encrypted PASETO v4.local token.
81    pub fn issue_token(
82        &self,
83        subject: &str,
84        additional_claims: Option<&HashMap<String, String>>,
85    ) -> Result<String> {
86        if subject.is_empty() {
87            return Err(AuthError::validation("Subject cannot be empty"));
88        }
89
90        let mut claims = Claims::new()
91            .map_err(|e| AuthError::crypto(format!("Failed to create claims: {e}")))?;
92
93        claims
94            .subject(subject)
95            .map_err(|e| AuthError::crypto(format!("Failed to set subject: {e}")))?;
96        claims
97            .issuer(&self.config.issuer)
98            .map_err(|e| AuthError::crypto(format!("Failed to set issuer: {e}")))?;
99        claims
100            .token_identifier(&uuid::Uuid::new_v4().to_string())
101            .map_err(|e| AuthError::crypto(format!("Failed to set jti: {e}")))?;
102
103        if let Some(ref aud) = self.config.audience {
104            claims
105                .audience(aud)
106                .map_err(|e| AuthError::crypto(format!("Failed to set audience: {e}")))?;
107        }
108
109        if let Some(extra) = additional_claims {
110            for (key, value) in extra {
111                claims
112                    .add_additional(key, value.clone())
113                    .map_err(|e| AuthError::crypto(format!("Failed to add claim '{key}': {e}")))?;
114            }
115        }
116
117        let footer = match self.config.footer.as_deref() {
118            Some(f) => {
119                let mut ft = Footer::new();
120                ft.add_additional("data", f)
121                    .map_err(|e| AuthError::crypto(format!("Invalid PASETO footer: {e}")))?;
122                Some(ft)
123            }
124            None => None,
125        };
126
127        local::encrypt(&self.key, &claims, footer.as_ref(), None)
128            .map_err(|e| AuthError::crypto(format!("PASETO encryption failed: {e}")))
129    }
130
131    /// Decrypt and validate a PASETO v4.local token.
132    pub fn validate_token(&self, token: &str) -> Result<PasetoToken> {
133        if !token.starts_with("v4.local.") {
134            return Err(AuthError::validation("Not a v4.local PASETO token"));
135        }
136
137        let validation_rules = ClaimsValidationRules::new();
138        let untrusted = UntrustedToken::<Local, V4>::try_from(token)
139            .map_err(|e| AuthError::validation(format!("Invalid PASETO token format: {e}")))?;
140
141        let footer = match self.config.footer.as_deref() {
142            Some(f) => {
143                let mut ft = Footer::new();
144                ft.add_additional("data", f)
145                    .map_err(|e| AuthError::validation(format!("Invalid PASETO footer: {e}")))?;
146                Some(ft)
147            }
148            None => None,
149        };
150
151        let trusted = local::decrypt(
152            &self.key,
153            &untrusted,
154            &validation_rules,
155            footer.as_ref(),
156            None,
157        )
158        .map_err(|e| AuthError::validation(format!("PASETO decryption/validation failed: {e}")))?;
159
160        let payload = trusted
161            .payload_claims()
162            .ok_or_else(|| AuthError::validation("PASETO token has no claims"))?;
163
164        let subject = payload
165            .get_claim("sub")
166            .and_then(|v| v.as_str())
167            .unwrap_or_default()
168            .to_string();
169        let issuer = payload
170            .get_claim("iss")
171            .and_then(|v| v.as_str())
172            .unwrap_or_default()
173            .to_string();
174        let token_id = payload
175            .get_claim("jti")
176            .and_then(|v| v.as_str())
177            .map(|s| s.to_string());
178        let audience = payload
179            .get_claim("aud")
180            .and_then(|v| v.as_str())
181            .map(|s| s.to_string());
182
183        if !self.config.issuer.is_empty() && issuer != self.config.issuer {
184            return Err(AuthError::validation(format!(
185                "Issuer mismatch: expected '{}', got '{}'",
186                self.config.issuer, issuer
187            )));
188        }
189
190        Ok(PasetoToken {
191            subject,
192            issuer,
193            token_id,
194            audience,
195            custom_claims: HashMap::new(),
196        })
197    }
198}
199
200/// Generate a new random 32-byte key for PASETO v4.local, returned as hex.
201pub fn generate_local_key_hex() -> Result<String> {
202    let key = SymmetricKey::<V4>::generate()
203        .map_err(|e| AuthError::crypto(format!("Failed to generate key: {e}")))?;
204    Ok(hex::encode(key.as_bytes()))
205}
206
207#[cfg(test)]
208mod tests {
209    use super::*;
210
211    fn default_manager() -> PasetoLocalManager {
212        PasetoLocalManager::new(PasetoConfig::default()).unwrap()
213    }
214
215    #[test]
216    fn test_issue_and_validate_token() {
217        let mgr = default_manager();
218        let token = mgr.issue_token("user-42", None).unwrap();
219        assert!(token.starts_with("v4.local."));
220        let decoded = mgr.validate_token(&token).unwrap();
221        assert_eq!(decoded.subject, "user-42");
222        assert_eq!(decoded.issuer, "auth-framework");
223        assert!(decoded.token_id.is_some());
224    }
225
226    #[test]
227    fn test_issue_with_custom_claims() {
228        let mgr = default_manager();
229        let mut extra = HashMap::new();
230        extra.insert("role".to_string(), "admin".to_string());
231        let token = mgr.issue_token("user-1", Some(&extra)).unwrap();
232        let decoded = mgr.validate_token(&token).unwrap();
233        assert_eq!(decoded.subject, "user-1");
234    }
235
236    #[test]
237    fn test_issue_with_audience() {
238        let config = PasetoConfig {
239            audience: Some("https://api.example.com".to_string()),
240            ..PasetoConfig::default()
241        };
242        let mgr = PasetoLocalManager::new(config).unwrap();
243        let token = mgr.issue_token("user-1", None).unwrap();
244        let decoded = mgr.validate_token(&token).unwrap();
245        assert_eq!(decoded.audience.as_deref(), Some("https://api.example.com"));
246    }
247
248    #[test]
249    fn test_reject_empty_subject() {
250        let mgr = default_manager();
251        assert!(mgr.issue_token("", None).is_err());
252    }
253
254    #[test]
255    fn test_reject_wrong_prefix() {
256        let mgr = default_manager();
257        assert!(mgr.validate_token("v4.public.garbage").is_err());
258    }
259
260    #[test]
261    fn test_reject_tampered_token() {
262        let mgr = default_manager();
263        let token = mgr.issue_token("user-1", None).unwrap();
264        let tampered = format!("{}tampered", token);
265        assert!(mgr.validate_token(&tampered).is_err());
266    }
267
268    #[test]
269    fn test_different_keys_reject() {
270        let mgr1 = default_manager();
271        let mgr2 = default_manager();
272        let token = mgr1.issue_token("user-1", None).unwrap();
273        assert!(mgr2.validate_token(&token).is_err());
274    }
275
276    #[test]
277    fn test_from_key_bytes_roundtrip() {
278        let key_bytes = [42u8; 32];
279        let config = PasetoConfig::default();
280        let mgr = PasetoLocalManager::from_key_bytes(config.clone(), &key_bytes).unwrap();
281        let token = mgr.issue_token("user-1", None).unwrap();
282        let mgr2 = PasetoLocalManager::from_key_bytes(config, &key_bytes).unwrap();
283        let decoded = mgr2.validate_token(&token).unwrap();
284        assert_eq!(decoded.subject, "user-1");
285    }
286
287    #[test]
288    fn test_issuer_mismatch_rejected() {
289        let key_bytes = [99u8; 32];
290        let cfg_a = PasetoConfig {
291            issuer: "server-a".to_string(),
292            ..PasetoConfig::default()
293        };
294        let cfg_b = PasetoConfig {
295            issuer: "server-b".to_string(),
296            ..PasetoConfig::default()
297        };
298        let mgr_a = PasetoLocalManager::from_key_bytes(cfg_a, &key_bytes).unwrap();
299        let mgr_b = PasetoLocalManager::from_key_bytes(cfg_b, &key_bytes).unwrap();
300        let token = mgr_a.issue_token("user-1", None).unwrap();
301        assert!(mgr_b.validate_token(&token).is_err());
302    }
303
304    #[test]
305    fn test_with_footer() {
306        let config = PasetoConfig {
307            footer: Some("key-id:v1".to_string()),
308            ..PasetoConfig::default()
309        };
310        let mgr = PasetoLocalManager::new(config).unwrap();
311        let token = mgr.issue_token("user-1", None).unwrap();
312        let decoded = mgr.validate_token(&token).unwrap();
313        assert_eq!(decoded.subject, "user-1");
314    }
315
316    #[test]
317    fn test_footer_mismatch_rejected() {
318        let key_bytes = [77u8; 32];
319        let cfg1 = PasetoConfig {
320            footer: Some("footer-a".to_string()),
321            ..PasetoConfig::default()
322        };
323        let cfg2 = PasetoConfig {
324            footer: Some("footer-b".to_string()),
325            ..PasetoConfig::default()
326        };
327        let mgr1 = PasetoLocalManager::from_key_bytes(cfg1, &key_bytes).unwrap();
328        let mgr2 = PasetoLocalManager::from_key_bytes(cfg2, &key_bytes).unwrap();
329        let token = mgr1.issue_token("user-1", None).unwrap();
330        assert!(mgr2.validate_token(&token).is_err());
331    }
332
333    #[test]
334    fn test_generate_local_key_hex() {
335        let key1 = generate_local_key_hex().unwrap();
336        let key2 = generate_local_key_hex().unwrap();
337        assert_eq!(key1.len(), 64);
338        assert_ne!(key1, key2);
339    }
340
341    #[test]
342    fn test_default_config() {
343        let config = PasetoConfig::default();
344        assert_eq!(config.issuer, "auth-framework");
345        assert_eq!(config.token_lifetime, Duration::from_secs(3600));
346        assert!(config.audience.is_none());
347        assert!(config.footer.is_none());
348    }
349
350    /// Known-answer: a token minted by pasetors 0.7.7 (key = [42; 32], exp 2999)
351    /// must still decrypt after the upgrade to 0.8.
352    #[test]
353    fn test_token_minted_by_pasetors_0_7_still_validates() {
354        const KNOWN_TOKEN: &str = "v4.local.BDJ3EJ7xkeAZ7EgKJizNVJKVctrjVQ3iv2AcJvnDqrs__PWLUjaQgFYyZMtUDlgtA6hlzCeAmQrmu5HbgcACobjvsOGBhFQgFYoKboZCmVnKDYl5Zyq8O7BZybOf-6nurk4g6VKxKeH6p4vWQjjd0RIpsbtB5shoX3OebrHoXPIW04JE3aztIId3-XZ22cvGpOPcQjjUSqIaf9UOK8__3oiVnBMrZmD4R6ZK4n6r083cHl7DRRl5d-TxoRgrWXpaI64Cjsg";
355        let mgr = PasetoLocalManager::from_key_bytes(PasetoConfig::default(), &[42u8; 32]).unwrap();
356        let decoded = mgr.validate_token(KNOWN_TOKEN).unwrap();
357        assert_eq!(decoded.subject, "kat-user");
358        assert_eq!(decoded.issuer, "auth-framework");
359    }
360}