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.last().expect("parts.len() >= 2 was checked above");
276
277        // If the last part is empty, there is no key-binding JWT.
278        // If the last part looks like a JWT (has dots), treat it as KB-JWT.
279        let (disclosure_parts, kb_jwt) = if last.is_empty() {
280            (&parts[1..parts.len() - 1], None)
281        } else if last.chars().filter(|&c| c == '.').count() == 2 {
282            (&parts[1..parts.len() - 1], Some(last.to_string()))
283        } else {
284            (&parts[1..], None)
285        };
286
287        let disclosures = disclosure_parts
288            .iter()
289            .filter(|s| !s.is_empty())
290            .map(|s| s.to_string())
291            .collect();
292
293        Ok((jwt, disclosures, kb_jwt))
294    }
295
296    /// Verify an SD-JWT and return the disclosed claims.
297    ///
298    /// * `sd_jwt_str` — the compact SD-JWT string.
299    /// * `verification_key` — the symmetric key or public key for signature verification.
300    pub fn verify(&self, sd_jwt_str: &str, verification_key: &str) -> Result<VerifiedSdJwt> {
301        let (jwt, disclosure_strings, kb_jwt) = Self::parse(sd_jwt_str)?;
302
303        // Verify JWT signature and decode payload.
304        let key = jsonwebtoken::DecodingKey::from_secret(verification_key.as_bytes());
305        let mut validation = jsonwebtoken::Validation::new(self.config.signing_algorithm);
306        validation.set_required_spec_claims::<&str>(&[]);
307        validation.validate_exp = true;
308        validation.set_issuer(&[&self.config.issuer]);
309
310        let token_data = jsonwebtoken::decode::<serde_json::Map<String, serde_json::Value>>(
311            &jwt,
312            &key,
313            &validation,
314        )
315        .map_err(|e| AuthError::token(format!("SD-JWT signature verification failed: {e}")))?;
316
317        let mut payload = token_data.claims;
318
319        // Extract `_sd` digests and `_sd_alg`.
320        let sd_digests: Vec<String> = payload
321            .remove("_sd")
322            .map(|v| {
323                v.as_array()
324                    .unwrap_or(&vec![])
325                    .iter()
326                    .filter_map(|item| item.as_str().map(|s| s.to_string()))
327                    .collect()
328            })
329            .unwrap_or_default();
330
331        let _sd_alg = payload.remove("_sd_alg");
332
333        // Process disclosures: decode, hash, and match against `_sd`.
334        let mut disclosed_claims = HashMap::new();
335        for disclosure_str in &disclosure_strings {
336            let decoded_bytes = URL_SAFE_NO_PAD
337                .decode(disclosure_str.as_bytes())
338                .map_err(|e| AuthError::validation(format!("Invalid disclosure encoding: {e}")))?;
339
340            let disclosure_array: serde_json::Value = serde_json::from_slice(&decoded_bytes)
341                .map_err(|e| AuthError::validation(format!("Invalid disclosure JSON: {e}")))?;
342
343            let arr = disclosure_array
344                .as_array()
345                .ok_or_else(|| AuthError::validation("Disclosure must be a JSON array"))?;
346
347            if arr.len() != 3 {
348                return Err(AuthError::validation(
349                    "Disclosure array must have exactly 3 elements [salt, name, value]",
350                ));
351            }
352
353            let claim_name = arr[1]
354                .as_str()
355                .ok_or_else(|| AuthError::validation("Disclosure claim name must be a string"))?;
356            let claim_value = &arr[2];
357
358            // Verify the disclosure hash is in the `_sd` array.
359            let hash = self.config.hash_algorithm.digest(disclosure_str.as_bytes());
360            let digest = URL_SAFE_NO_PAD.encode(&hash);
361
362            if !sd_digests.contains(&digest) {
363                return Err(AuthError::validation(format!(
364                    "Disclosure for '{}' does not match any _sd digest",
365                    claim_name,
366                )));
367            }
368
369            disclosed_claims.insert(claim_name.to_string(), claim_value.clone());
370        }
371
372        Ok(VerifiedSdJwt {
373            plaintext_claims: payload,
374            disclosed_claims,
375            key_binding_jwt: kb_jwt,
376        })
377    }
378}
379
380/// Result of verifying an SD-JWT.
381#[derive(Debug, Clone)]
382pub struct VerifiedSdJwt {
383    /// Claims that were in the JWT payload in the clear.
384    pub plaintext_claims: serde_json::Map<String, serde_json::Value>,
385    /// Claims reconstructed from the presented disclosures.
386    pub disclosed_claims: HashMap<String, serde_json::Value>,
387    /// The optional key-binding JWT, if present.
388    pub key_binding_jwt: Option<String>,
389}
390
391impl VerifiedSdJwt {
392    /// Get a claim by name, checking disclosed claims first, then plaintext.
393    pub fn get_claim(&self, name: &str) -> Option<&serde_json::Value> {
394        self.disclosed_claims
395            .get(name)
396            .or_else(|| self.plaintext_claims.get(name))
397    }
398
399    /// Merge all claims into a single map.
400    pub fn all_claims(&self) -> serde_json::Map<String, serde_json::Value> {
401        let mut merged = self.plaintext_claims.clone();
402        for (k, v) in &self.disclosed_claims {
403            merged.insert(k.clone(), v.clone());
404        }
405        merged
406    }
407}
408
409#[cfg(test)]
410mod tests {
411    use super::*;
412
413    const TEST_KEY: &str = "test-signing-key-at-least-256-bits-long!!";
414
415    fn test_config() -> SdJwtConfig {
416        SdJwtConfig {
417            lifetime_secs: 3600,
418            ..SdJwtConfig::default()
419        }
420    }
421
422    fn sample_claims() -> serde_json::Map<String, serde_json::Value> {
423        let mut claims = serde_json::Map::new();
424        claims.insert("sub".into(), serde_json::json!("user-42"));
425        claims.insert("email".into(), serde_json::json!("user@example.com"));
426        claims.insert("name".into(), serde_json::json!("Alice"));
427        claims.insert(
428            "address".into(),
429            serde_json::json!({"street": "123 Main St", "city": "Springfield"}),
430        );
431        claims
432    }
433
434    #[test]
435    fn test_issue_and_serialize() {
436        let issuer = SdJwtIssuer::new(test_config());
437        let claims = sample_claims();
438        let sd_jwt = issuer
439            .issue(&claims, &["email", "address"], TEST_KEY)
440            .unwrap();
441
442        assert!(!sd_jwt.jwt.is_empty());
443        assert_eq!(sd_jwt.disclosures.len(), 2);
444
445        let serialized = sd_jwt.serialize();
446        // JWT + 2 disclosures + trailing tilde
447        assert_eq!(serialized.matches('~').count(), 3);
448    }
449
450    #[test]
451    fn test_issue_no_sd_claims() {
452        let issuer = SdJwtIssuer::new(test_config());
453        let claims = sample_claims();
454        let sd_jwt = issuer.issue(&claims, &[], TEST_KEY).unwrap();
455
456        assert!(sd_jwt.disclosures.is_empty());
457        let serialized = sd_jwt.serialize();
458        assert!(serialized.ends_with('~'));
459    }
460
461    #[test]
462    fn test_full_disclosure_roundtrip() {
463        let config = test_config();
464        let issuer = SdJwtIssuer::new(config.clone());
465        let verifier = SdJwtVerifier::new(config);
466        let claims = sample_claims();
467
468        let sd_jwt = issuer.issue(&claims, &["email", "name"], TEST_KEY).unwrap();
469        let serialized = sd_jwt.serialize();
470
471        let verified = verifier.verify(&serialized, TEST_KEY).unwrap();
472
473        assert_eq!(verified.get_claim("sub").unwrap(), "user-42");
474        assert_eq!(verified.get_claim("email").unwrap(), "user@example.com");
475        assert_eq!(verified.get_claim("name").unwrap(), "Alice");
476    }
477
478    #[test]
479    fn test_selective_disclosure() {
480        let config = test_config();
481        let issuer = SdJwtIssuer::new(config.clone());
482        let verifier = SdJwtVerifier::new(config);
483        let claims = sample_claims();
484
485        let sd_jwt = issuer
486            .issue(&claims, &["email", "name", "address"], TEST_KEY)
487            .unwrap();
488
489        // Present only "email", omitting "name" and "address"
490        let presentation = sd_jwt.present(&["email"]);
491
492        let verified = verifier.verify(&presentation, TEST_KEY).unwrap();
493
494        // "sub" is plaintext — always visible
495        assert_eq!(verified.get_claim("sub").unwrap(), "user-42");
496        // "email" was disclosed
497        assert_eq!(verified.get_claim("email").unwrap(), "user@example.com");
498        // "name" and "address" were NOT disclosed
499        assert!(verified.get_claim("name").is_none());
500        assert!(verified.get_claim("address").is_none());
501    }
502
503    #[test]
504    fn test_all_claims_merged() {
505        let config = test_config();
506        let issuer = SdJwtIssuer::new(config.clone());
507        let verifier = SdJwtVerifier::new(config);
508        let claims = sample_claims();
509
510        let sd_jwt = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
511        let serialized = sd_jwt.serialize();
512
513        let verified = verifier.verify(&serialized, TEST_KEY).unwrap();
514        let merged = verified.all_claims();
515
516        assert!(merged.contains_key("sub"));
517        assert!(merged.contains_key("email"));
518        assert!(merged.contains_key("iss"));
519        assert!(merged.contains_key("iat"));
520        assert!(merged.contains_key("exp"));
521    }
522
523    #[test]
524    fn test_reject_empty_claims() {
525        let issuer = SdJwtIssuer::new(test_config());
526        let claims = serde_json::Map::new();
527        assert!(issuer.issue(&claims, &[], TEST_KEY).is_err());
528    }
529
530    #[test]
531    fn test_reject_wrong_key() {
532        let config = test_config();
533        let issuer = SdJwtIssuer::new(config.clone());
534        let verifier = SdJwtVerifier::new(config);
535        let claims = sample_claims();
536
537        let sd_jwt = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
538        let serialized = sd_jwt.serialize();
539
540        assert!(
541            verifier
542                .verify(&serialized, "wrong-key-wrong-key-wrong-key!!!")
543                .is_err()
544        );
545    }
546
547    #[test]
548    fn test_reject_forged_disclosure() {
549        let config = test_config();
550        let issuer = SdJwtIssuer::new(config.clone());
551        let verifier = SdJwtVerifier::new(config);
552        let claims = sample_claims();
553
554        let sd_jwt = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
555
556        // Forge a disclosure that isn't in the _sd array
557        let forged = serde_json::json!(["fakesalt", "role", "admin"]);
558        let forged_encoded = URL_SAFE_NO_PAD.encode(forged.to_string().as_bytes());
559        let forged_sd_jwt = format!("{}~{}~", sd_jwt.jwt, forged_encoded);
560
561        assert!(verifier.verify(&forged_sd_jwt, TEST_KEY).is_err());
562    }
563
564    #[test]
565    fn test_parse_components() {
566        let input = "eyJ0eXAi.payload.sig~disc1~disc2~";
567        let (jwt, disclosures, kb) = SdJwtVerifier::parse(input).unwrap();
568        assert_eq!(jwt, "eyJ0eXAi.payload.sig");
569        assert_eq!(disclosures.len(), 2);
570        assert!(kb.is_none());
571    }
572
573    #[test]
574    fn test_parse_with_kb_jwt() {
575        let input = "eyJ0eXAi.payload.sig~disc1~header.payload.signature";
576        let (jwt, disclosures, kb) = SdJwtVerifier::parse(input).unwrap();
577        assert_eq!(jwt, "eyJ0eXAi.payload.sig");
578        assert_eq!(disclosures.len(), 1);
579        assert_eq!(kb.unwrap(), "header.payload.signature");
580    }
581
582    #[test]
583    fn test_disclosure_uniqueness() {
584        let issuer = SdJwtIssuer::new(test_config());
585        let claims = sample_claims();
586
587        let sd_jwt1 = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
588        let sd_jwt2 = issuer.issue(&claims, &["email"], TEST_KEY).unwrap();
589
590        // Different salts produce different disclosures
591        assert_ne!(
592            sd_jwt1.disclosures[0].encoded,
593            sd_jwt2.disclosures[0].encoded
594        );
595        assert_ne!(sd_jwt1.disclosures[0].digest, sd_jwt2.disclosures[0].digest);
596    }
597
598    #[test]
599    fn test_complex_claim_value() {
600        let config = test_config();
601        let issuer = SdJwtIssuer::new(config.clone());
602        let verifier = SdJwtVerifier::new(config);
603
604        let mut claims = serde_json::Map::new();
605        claims.insert("sub".into(), serde_json::json!("user-1"));
606        claims.insert(
607            "address".into(),
608            serde_json::json!({
609                "street": "123 Main St",
610                "city": "Springfield",
611                "zip": "62701"
612            }),
613        );
614
615        let sd_jwt = issuer.issue(&claims, &["address"], TEST_KEY).unwrap();
616        let serialized = sd_jwt.serialize();
617        let verified = verifier.verify(&serialized, TEST_KEY).unwrap();
618
619        let addr = verified.get_claim("address").unwrap();
620        assert_eq!(addr["city"], "Springfield");
621        assert_eq!(addr["zip"], "62701");
622    }
623}