Skip to main content

auth_framework/protocols/
sd_jwt.rs

1//! SD-JWT (Selective Disclosure JWT) implementation.
2//!
3//! Implements the IETF SD-JWT specification (draft-ietf-oauth-selective-disclosure-jwt)
4//! for creating JWTs whose claims can be selectively disclosed by the holder.
5//!
6//! # Architecture
7//!
8//! - **Issuer**: Creates an SD-JWT with selectively disclosable claims hashed into
9//!   the `_sd` array. Each claim becomes a separate disclosure.
10//! - **Holder**: Receives the full SD-JWT and can present a subset of disclosures
11//!   to a verifier, revealing only the claims they choose.
12//! - **Verifier**: Validates the JWT signature and reconstructs disclosed claims
13//!   by matching disclosure hashes against the `_sd` array.
14//!
15//! # Example
16//!
17//! ```rust,no_run
18//! use auth_framework::protocols::sd_jwt::{SdJwtIssuer, SdJwtConfig};
19//!
20//! let config = SdJwtConfig::default();
21//! let issuer = SdJwtIssuer::new(config);
22//!
23//! let mut claims = serde_json::Map::new();
24//! claims.insert("sub".into(), serde_json::json!("user-42"));
25//! claims.insert("email".into(), serde_json::json!("user@example.com"));
26//!
27//! // "email" is selectively disclosable; "sub" stays in the clear
28//! let sd_jwt = issuer.issue(
29//!     &claims,
30//!     &["email"],
31//!     "signing-secret-key",
32//! ).unwrap();
33//! ```
34
35use crate::errors::{AuthError, Result};
36use base64::Engine;
37use base64::engine::general_purpose::URL_SAFE_NO_PAD;
38use serde::{Deserialize, Serialize};
39use sha2::{Digest, Sha256};
40use std::collections::HashMap;
41
42/// Hash algorithm used for disclosure digests.
43#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
44pub enum SdHashAlgorithm {
45    /// SHA-256 (default, recommended).
46    #[serde(rename = "sha-256")]
47    #[default]
48    Sha256,
49}
50
51impl SdHashAlgorithm {
52    /// Return the `_sd_alg` string value.
53    pub fn as_str(&self) -> &'static str {
54        match self {
55            Self::Sha256 => "sha-256",
56        }
57    }
58
59    /// Compute the digest of `input` using this algorithm.
60    fn digest(&self, input: &[u8]) -> Vec<u8> {
61        match self {
62            Self::Sha256 => Sha256::digest(input).to_vec(),
63        }
64    }
65}
66
67/// Configuration for SD-JWT operations.
68#[derive(Debug, Clone, Serialize, Deserialize)]
69pub struct SdJwtConfig {
70    /// Hash algorithm for disclosure digests.
71    pub hash_algorithm: SdHashAlgorithm,
72    /// JWT signing algorithm.
73    pub signing_algorithm: jsonwebtoken::Algorithm,
74    /// Issuer claim value.
75    pub issuer: String,
76    /// Token lifetime in seconds.
77    pub lifetime_secs: u64,
78    /// Salt length in bytes (minimum 16 recommended by spec).
79    pub salt_length: usize,
80}
81
82impl Default for SdJwtConfig {
83    fn default() -> Self {
84        Self {
85            hash_algorithm: SdHashAlgorithm::default(),
86            signing_algorithm: jsonwebtoken::Algorithm::HS256,
87            issuer: "auth-framework".to_string(),
88            lifetime_secs: 3600,
89            salt_length: 16,
90        }
91    }
92}
93
94/// A single disclosure: the base64url-encoded `[salt, claim_name, claim_value]` array.
95#[derive(Debug, Clone)]
96pub struct Disclosure {
97    /// The base64url-encoded disclosure string.
98    pub encoded: String,
99    /// The claim name this disclosure reveals.
100    pub claim_name: String,
101    /// The claim value.
102    pub claim_value: serde_json::Value,
103    /// The hash digest of the encoded disclosure (for inclusion in `_sd`).
104    pub digest: String,
105}
106
107/// The issued SD-JWT: a compact JWT, the tilde-separated disclosures, and
108/// an optional key-binding JWT.
109#[derive(Debug, Clone)]
110pub struct SdJwt {
111    /// The signed JWT containing `_sd` digests.
112    pub jwt: String,
113    /// All disclosures produced by the issuer.
114    pub disclosures: Vec<Disclosure>,
115    /// Optional holder key-binding JWT.
116    pub key_binding_jwt: Option<String>,
117}
118
119impl SdJwt {
120    /// Serialize to the SD-JWT compact format: `<JWT>~<Disclosure1>~...~<DisclosureN>~[KB-JWT]`.
121    pub fn serialize(&self) -> String {
122        let mut out = self.jwt.clone();
123        for d in &self.disclosures {
124            out.push('~');
125            out.push_str(&d.encoded);
126        }
127        out.push('~');
128        if let Some(ref kb) = self.key_binding_jwt {
129            out.push_str(kb);
130        }
131        out
132    }
133
134    /// Create a presentation with only the selected claim names disclosed.
135    pub fn present(&self, claims_to_disclose: &[&str]) -> String {
136        let mut out = self.jwt.clone();
137        for d in &self.disclosures {
138            if claims_to_disclose.contains(&d.claim_name.as_str()) {
139                out.push('~');
140                out.push_str(&d.encoded);
141            }
142        }
143        out.push('~');
144        if let Some(ref kb) = self.key_binding_jwt {
145            out.push_str(kb);
146        }
147        out
148    }
149}
150
151/// SD-JWT issuer: creates SD-JWTs with selectively disclosable claims.
152pub struct SdJwtIssuer {
153    config: SdJwtConfig,
154}
155
156impl SdJwtIssuer {
157    /// Create a new issuer with the given configuration.
158    pub fn new(config: SdJwtConfig) -> Self {
159        Self { config }
160    }
161
162    /// Generate a cryptographically random salt.
163    fn generate_salt(&self) -> Result<String> {
164        let mut salt = vec![0u8; self.config.salt_length];
165        ring::rand::SecureRandom::fill(&ring::rand::SystemRandom::new(), &mut salt)
166            .map_err(|_| AuthError::crypto("Failed to generate random salt"))?;
167        Ok(URL_SAFE_NO_PAD.encode(&salt))
168    }
169
170    /// Build a disclosure for a single claim and return its digest.
171    fn create_disclosure(
172        &self,
173        claim_name: &str,
174        claim_value: &serde_json::Value,
175    ) -> Result<Disclosure> {
176        let salt = self.generate_salt()?;
177        let array = serde_json::json!([salt, claim_name, claim_value]);
178        let encoded = URL_SAFE_NO_PAD.encode(array.to_string().as_bytes());
179        let hash = self.config.hash_algorithm.digest(encoded.as_bytes());
180        let digest = URL_SAFE_NO_PAD.encode(&hash);
181
182        Ok(Disclosure {
183            encoded,
184            claim_name: claim_name.to_string(),
185            claim_value: claim_value.clone(),
186            digest,
187        })
188    }
189
190    /// Issue an SD-JWT.
191    ///
192    /// * `claims` — all claims to include in the token.
193    /// * `sd_claims` — names of claims that should be selectively disclosable.
194    ///   Claims not listed here are included in the JWT payload in the clear.
195    /// * `signing_key` — the symmetric key (for HMAC algorithms) or PEM-encoded
196    ///   private key (for RSA/EC algorithms).
197    pub fn issue(
198        &self,
199        claims: &serde_json::Map<String, serde_json::Value>,
200        sd_claims: &[&str],
201        signing_key: &str,
202    ) -> Result<SdJwt> {
203        if claims.is_empty() {
204            return Err(AuthError::validation("Claims map cannot be empty"));
205        }
206
207        let mut payload = serde_json::Map::new();
208        let mut disclosures = Vec::new();
209        let mut sd_digests: Vec<serde_json::Value> = Vec::new();
210
211        // Separate plaintext claims from selectively-disclosable claims.
212        for (name, value) in claims {
213            if sd_claims.contains(&name.as_str()) {
214                let disclosure = self.create_disclosure(name, value)?;
215                sd_digests.push(serde_json::Value::String(disclosure.digest.clone()));
216                disclosures.push(disclosure);
217            } else {
218                payload.insert(name.clone(), value.clone());
219            }
220        }
221
222        // Add standard JWT claims.
223        let now = chrono::Utc::now().timestamp() as u64;
224        payload.insert("iss".to_string(), serde_json::json!(self.config.issuer));
225        payload.insert("iat".to_string(), serde_json::json!(now));
226        payload.insert(
227            "exp".to_string(),
228            serde_json::json!(now + self.config.lifetime_secs),
229        );
230
231        // Add the `_sd` array and `_sd_alg`.
232        if !sd_digests.is_empty() {
233            payload.insert("_sd".to_string(), serde_json::Value::Array(sd_digests));
234            payload.insert(
235                "_sd_alg".to_string(),
236                serde_json::json!(self.config.hash_algorithm.as_str()),
237            );
238        }
239
240        // Sign the JWT.
241        let header = jsonwebtoken::Header::new(self.config.signing_algorithm);
242        let key = jsonwebtoken::EncodingKey::from_secret(signing_key.as_bytes());
243        let jwt = jsonwebtoken::encode(&header, &payload, &key)
244            .map_err(|e| AuthError::crypto(format!("SD-JWT signing failed: {e}")))?;
245
246        Ok(SdJwt {
247            jwt,
248            disclosures,
249            key_binding_jwt: None,
250        })
251    }
252}
253
254/// SD-JWT verifier: validates SD-JWTs and reconstructs disclosed claims.
255pub struct SdJwtVerifier {
256    config: SdJwtConfig,
257}
258
259impl SdJwtVerifier {
260    /// Create a new verifier.
261    pub fn new(config: SdJwtConfig) -> Self {
262        Self { config }
263    }
264
265    /// Parse a serialized SD-JWT string into its components.
266    pub fn parse(input: &str) -> Result<(String, Vec<String>, Option<String>)> {
267        let parts: Vec<&str> = input.split('~').collect();
268        if parts.len() < 2 {
269            return Err(AuthError::validation(
270                "Invalid SD-JWT format: must contain at least JWT~",
271            ));
272        }
273
274        let jwt = parts[0].to_string();
275        let last = *parts
276            .last()
277            .ok_or_else(|| AuthError::validation("Invalid SD-JWT format: no parts"))?;
278
279        // If the last part is empty, there is no key-binding JWT.
280        // If the last part looks like a JWT (has dots), treat it as KB-JWT.
281        let (disclosure_parts, kb_jwt) = if last.is_empty() {
282            (&parts[1..parts.len() - 1], None)
283        } else if last.chars().filter(|&c| c == '.').count() == 2 {
284            (&parts[1..parts.len() - 1], Some(last.to_string()))
285        } else {
286            (&parts[1..], None)
287        };
288
289        let disclosures = disclosure_parts
290            .iter()
291            .filter(|s| !s.is_empty())
292            .map(|s| s.to_string())
293            .collect();
294
295        Ok((jwt, disclosures, kb_jwt))
296    }
297
298    /// Verify an SD-JWT and return the disclosed claims.
299    ///
300    /// * `sd_jwt_str` — the compact SD-JWT string.
301    /// * `verification_key` — the symmetric key or public key for signature verification.
302    pub fn verify(&self, sd_jwt_str: &str, verification_key: &str) -> Result<VerifiedSdJwt> {
303        let (jwt, disclosure_strings, kb_jwt) = Self::parse(sd_jwt_str)?;
304
305        // Verify JWT signature and decode payload.
306        let key = jsonwebtoken::DecodingKey::from_secret(verification_key.as_bytes());
307        let mut validation = jsonwebtoken::Validation::new(self.config.signing_algorithm);
308        validation.set_required_spec_claims::<&str>(&[]);
309        validation.validate_exp = true;
310        validation.set_issuer(&[&self.config.issuer]);
311
312        let token_data = jsonwebtoken::decode::<serde_json::Map<String, serde_json::Value>>(
313            &jwt,
314            &key,
315            &validation,
316        )
317        .map_err(|e| AuthError::token(format!("SD-JWT signature verification failed: {e}")))?;
318
319        let mut payload = token_data.claims;
320
321        // Extract `_sd` digests and `_sd_alg`.
322        let sd_digests: Vec<String> = payload
323            .remove("_sd")
324            .map(|v| {
325                v.as_array()
326                    .unwrap_or(&vec![])
327                    .iter()
328                    .filter_map(|item| item.as_str().map(|s| s.to_string()))
329                    .collect()
330            })
331            .unwrap_or_default();
332
333        let _sd_alg = payload.remove("_sd_alg");
334
335        // Process disclosures: decode, hash, and match against `_sd`.
336        let mut disclosed_claims = HashMap::new();
337        for disclosure_str in &disclosure_strings {
338            let decoded_bytes = URL_SAFE_NO_PAD
339                .decode(disclosure_str.as_bytes())
340                .map_err(|e| AuthError::validation(format!("Invalid disclosure encoding: {e}")))?;
341
342            let disclosure_array: serde_json::Value = serde_json::from_slice(&decoded_bytes)
343                .map_err(|e| AuthError::validation(format!("Invalid disclosure JSON: {e}")))?;
344
345            let arr = disclosure_array
346                .as_array()
347                .ok_or_else(|| AuthError::validation("Disclosure must be a JSON array"))?;
348
349            if arr.len() != 3 {
350                return Err(AuthError::validation(
351                    "Disclosure array must have exactly 3 elements [salt, name, value]",
352                ));
353            }
354
355            let claim_name = arr[1]
356                .as_str()
357                .ok_or_else(|| AuthError::validation("Disclosure claim name must be a string"))?;
358            let claim_value = &arr[2];
359
360            // Verify the disclosure hash is in the `_sd` array.
361            let hash = self.config.hash_algorithm.digest(disclosure_str.as_bytes());
362            let digest = URL_SAFE_NO_PAD.encode(&hash);
363
364            if !sd_digests.contains(&digest) {
365                return Err(AuthError::validation(format!(
366                    "Disclosure for '{}' does not match any _sd digest",
367                    claim_name,
368                )));
369            }
370
371            disclosed_claims.insert(claim_name.to_string(), claim_value.clone());
372        }
373
374        Ok(VerifiedSdJwt {
375            plaintext_claims: payload,
376            disclosed_claims,
377            key_binding_jwt: kb_jwt,
378        })
379    }
380}
381
382/// Result of verifying an SD-JWT.
383#[derive(Debug, Clone)]
384pub struct VerifiedSdJwt {
385    /// Claims that were in the JWT payload in the clear.
386    pub plaintext_claims: serde_json::Map<String, serde_json::Value>,
387    /// Claims reconstructed from the presented disclosures.
388    pub disclosed_claims: HashMap<String, serde_json::Value>,
389    /// The optional key-binding JWT, if present.
390    pub key_binding_jwt: Option<String>,
391}
392
393impl VerifiedSdJwt {
394    /// Get a claim by name, checking disclosed claims first, then plaintext.
395    pub fn get_claim(&self, name: &str) -> Option<&serde_json::Value> {
396        self.disclosed_claims
397            .get(name)
398            .or_else(|| self.plaintext_claims.get(name))
399    }
400
401    /// Merge all claims into a single map.
402    pub fn all_claims(&self) -> serde_json::Map<String, serde_json::Value> {
403        let mut merged = self.plaintext_claims.clone();
404        for (k, v) in &self.disclosed_claims {
405            merged.insert(k.clone(), v.clone());
406        }
407        merged
408    }
409}
410
411#[cfg(test)]
412mod tests {
413    use super::*;
414
415    const TEST_KEY: &str = "test-signing-key-at-least-256-bits-long!!";
416
417    fn test_config() -> SdJwtConfig {
418        SdJwtConfig {
419            lifetime_secs: 3600,
420            ..SdJwtConfig::default()
421        }
422    }
423
424    fn sample_claims() -> serde_json::Map<String, serde_json::Value> {
425        let mut claims = serde_json::Map::new();
426        claims.insert("sub".into(), serde_json::json!("user-42"));
427        claims.insert("email".into(), serde_json::json!("user@example.com"));
428        claims.insert("name".into(), serde_json::json!("Alice"));
429        claims.insert(
430            "address".into(),
431            serde_json::json!({"street": "123 Main St", "city": "Springfield"}),
432        );
433        claims
434    }
435
436    #[test]
437    fn test_issue_and_serialize() {
438        let issuer = SdJwtIssuer::new(test_config());
439        let claims = sample_claims();
440        let sd_jwt = issuer
441            .issue(&claims, &["email", "address"], TEST_KEY)
442            .unwrap();
443
444        assert!(!sd_jwt.jwt.is_empty());
445        assert_eq!(sd_jwt.disclosures.len(), 2);
446
447        let serialized = sd_jwt.serialize();
448        // JWT + 2 disclosures + trailing tilde
449        assert_eq!(serialized.matches('~').count(), 3);
450    }
451
452    #[test]
453    fn test_issue_no_sd_claims() {
454        let issuer = SdJwtIssuer::new(test_config());
455        let claims = sample_claims();
456        let sd_jwt = issuer.issue(&claims, &[], TEST_KEY).unwrap();
457
458        assert!(sd_jwt.disclosures.is_empty());
459        let serialized = sd_jwt.serialize();
460        assert!(serialized.ends_with('~'));
461    }
462
463    #[test]
464    fn test_full_disclosure_roundtrip() {
465        let config = test_config();
466        let issuer = SdJwtIssuer::new(config.clone());
467        let verifier = SdJwtVerifier::new(config);
468        let claims = sample_claims();
469
470        let sd_jwt = issuer.issue(&claims, &["email", "name"], TEST_KEY).unwrap();
471        let serialized = sd_jwt.serialize();
472
473        let verified = verifier.verify(&serialized, TEST_KEY).unwrap();
474
475        assert_eq!(verified.get_claim("sub").unwrap(), "user-42");
476        assert_eq!(verified.get_claim("email").unwrap(), "user@example.com");
477        assert_eq!(verified.get_claim("name").unwrap(), "Alice");
478    }
479
480    #[test]
481    fn test_selective_disclosure() {
482        let config = test_config();
483        let issuer = SdJwtIssuer::new(config.clone());
484        let verifier = SdJwtVerifier::new(config);
485        let claims = sample_claims();
486
487        let sd_jwt = issuer
488            .issue(&claims, &["email", "name", "address"], TEST_KEY)
489            .unwrap();
490
491        // Present only "email", omitting "name" and "address"
492        let presentation = sd_jwt.present(&["email"]);
493
494        let verified = verifier.verify(&presentation, TEST_KEY).unwrap();
495
496        // "sub" is plaintext — always visible
497        assert_eq!(verified.get_claim("sub").unwrap(), "user-42");
498        // "email" was disclosed
499        assert_eq!(verified.get_claim("email").unwrap(), "user@example.com");
500        // "name" and "address" were NOT disclosed
501        assert!(verified.get_claim("name").is_none());
502        assert!(verified.get_claim("address").is_none());
503    }
504
505    #[test]
506    fn test_all_claims_merged() {
507        let config = test_config();
508        let issuer = SdJwtIssuer::new(config.clone());
509        let verifier = SdJwtVerifier::new(config);
510        let claims = sample_claims();
511
512        let sd_jwt = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
513        let serialized = sd_jwt.serialize();
514
515        let verified = verifier.verify(&serialized, TEST_KEY).unwrap();
516        let merged = verified.all_claims();
517
518        assert!(merged.contains_key("sub"));
519        assert!(merged.contains_key("email"));
520        assert!(merged.contains_key("iss"));
521        assert!(merged.contains_key("iat"));
522        assert!(merged.contains_key("exp"));
523    }
524
525    #[test]
526    fn test_reject_empty_claims() {
527        let issuer = SdJwtIssuer::new(test_config());
528        let claims = serde_json::Map::new();
529        assert!(issuer.issue(&claims, &[], TEST_KEY).is_err());
530    }
531
532    #[test]
533    fn test_reject_wrong_key() {
534        let config = test_config();
535        let issuer = SdJwtIssuer::new(config.clone());
536        let verifier = SdJwtVerifier::new(config);
537        let claims = sample_claims();
538
539        let sd_jwt = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
540        let serialized = sd_jwt.serialize();
541
542        assert!(
543            verifier
544                .verify(&serialized, "wrong-key-wrong-key-wrong-key!!!")
545                .is_err()
546        );
547    }
548
549    #[test]
550    fn test_reject_forged_disclosure() {
551        let config = test_config();
552        let issuer = SdJwtIssuer::new(config.clone());
553        let verifier = SdJwtVerifier::new(config);
554        let claims = sample_claims();
555
556        let sd_jwt = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
557
558        // Forge a disclosure that isn't in the _sd array
559        let forged = serde_json::json!(["fakesalt", "role", "admin"]);
560        let forged_encoded = URL_SAFE_NO_PAD.encode(forged.to_string().as_bytes());
561        let forged_sd_jwt = format!("{}~{}~", sd_jwt.jwt, forged_encoded);
562
563        assert!(verifier.verify(&forged_sd_jwt, TEST_KEY).is_err());
564    }
565
566    #[test]
567    fn test_parse_components() {
568        let input = "eyJ0eXAi.payload.sig~disc1~disc2~";
569        let (jwt, disclosures, kb) = SdJwtVerifier::parse(input).unwrap();
570        assert_eq!(jwt, "eyJ0eXAi.payload.sig");
571        assert_eq!(disclosures.len(), 2);
572        assert!(kb.is_none());
573    }
574
575    #[test]
576    fn test_parse_with_kb_jwt() {
577        let input = "eyJ0eXAi.payload.sig~disc1~header.payload.signature";
578        let (jwt, disclosures, kb) = SdJwtVerifier::parse(input).unwrap();
579        assert_eq!(jwt, "eyJ0eXAi.payload.sig");
580        assert_eq!(disclosures.len(), 1);
581        assert_eq!(kb.unwrap(), "header.payload.signature");
582    }
583
584    #[test]
585    fn test_disclosure_uniqueness() {
586        let issuer = SdJwtIssuer::new(test_config());
587        let claims = sample_claims();
588
589        let sd_jwt1 = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
590        let sd_jwt2 = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
591
592        // Different salts produce different disclosures
593        assert_ne!(
594            sd_jwt1.disclosures[0].encoded,
595            sd_jwt2.disclosures[0].encoded
596        );
597        assert_ne!(sd_jwt1.disclosures[0].digest, sd_jwt2.disclosures[0].digest);
598    }
599
600    #[test]
601    fn test_complex_claim_value() {
602        let config = test_config();
603        let issuer = SdJwtIssuer::new(config.clone());
604        let verifier = SdJwtVerifier::new(config);
605
606        let mut claims = serde_json::Map::new();
607        claims.insert("sub".into(), serde_json::json!("user-1"));
608        claims.insert(
609            "address".into(),
610            serde_json::json!({
611                "street": "123 Main St",
612                "city": "Springfield",
613                "zip": "62701"
614            }),
615        );
616
617        let sd_jwt = issuer.issue(&claims, &["address"], TEST_KEY).unwrap();
618        let serialized = sd_jwt.serialize();
619        let verified = verifier.verify(&serialized, TEST_KEY).unwrap();
620
621        let addr = verified.get_claim("address").unwrap();
622        assert_eq!(addr["city"], "Springfield");
623        assert_eq!(addr["zip"], "62701");
624    }
625}