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