identity_kit/vc/validation/
credential.rs1use std::collections::BTreeSet;
4
5use crate::did::Uri;
6use crate::jose::{CompactJws, DefaultVerifier, Jwk, JwsHeader, JwsVerifier};
7use crate::resolver::resolve_jws_key;
8use crate::vc::{Credential, CredentialV2, Jwt, JwtClaims, Party};
9
10use serde_json::Value;
11
12use super::{
13 CredentialStatus, CredentialValidationOptions, KeyReference, KeyResolver, KeyRole, StatusCheck,
14 StatusPolicy, TimeOptions, ValidationError, check_statuses, status_claim, status_claim_entry,
15};
16
17#[derive(Debug, Clone)]
20#[non_exhaustive]
21pub struct DecodedCredential {
22 pub header: JwsHeader,
24 pub claims: JwtClaims,
26 pub credential: Credential,
28}
29
30#[derive(Debug, Clone)]
32#[non_exhaustive]
33pub struct DecodedCredentialV2 {
34 pub header: JwsHeader,
36 pub claims: JwtClaims,
38 pub credential: CredentialV2,
40}
41
42pub struct JwtCredentialValidator<R, V = DefaultVerifier> {
103 resolver: R,
104 verifier: V,
105 status: Option<Box<dyn StatusCheck>>,
106}
107
108impl<R: KeyResolver, V: JwsVerifier> JwtCredentialValidator<R, V> {
109 pub fn new(resolver: R, verifier: V) -> Self {
112 Self {
113 resolver,
114 verifier,
115 status: None,
116 }
117 }
118
119 #[must_use]
121 pub fn with_status_check(mut self, check: impl StatusCheck + 'static) -> Self {
122 self.status = Some(Box::new(check));
123 self
124 }
125
126 pub fn resolver(&self) -> &R {
128 &self.resolver
129 }
130
131 pub fn verifier(&self) -> &V {
133 &self.verifier
134 }
135
136 pub fn has_status_check(&self) -> bool {
138 self.status.is_some()
139 }
140
141 pub async fn validate(
148 &self,
149 jwt: &Jwt,
150 options: &CredentialValidationOptions,
151 ) -> Result<DecodedCredential, ValidationError> {
152 let jws = jwt.decode()?;
153 let decoded = decode(&jws, &options.additional_typ)?;
154 let time = options.time.pinned();
156 let issuer = &decoded.credential.issuer;
157 let (reference, key) = self
158 .verify(&jws, KeyRole::Issuer, Some(issuer.id().as_str()), time)
159 .await?;
160 check_controller(issuer, &reference, &key, "issuer")?;
161 time.check_claims(&decoded.claims)?;
162 time.check(
163 Some(decoded.credential.issuance_date),
164 decoded.credential.expiration_date,
165 None,
166 )?;
167 let status = status_claim(&decoded.claims, options.status)?;
168 self.check_status(
169 decoded
170 .credential
171 .credential_status
172 .iter()
173 .map(CredentialStatus::Vcdm)
174 .chain(status.iter().map(status_claim_entry))
175 .collect(),
176 options.status,
177 time,
178 )
179 .await?;
180 Ok(decoded)
181 }
182
183 pub async fn validate_v2(
189 &self,
190 jwt: &Jwt,
191 options: &CredentialValidationOptions,
192 ) -> Result<DecodedCredentialV2, ValidationError> {
193 let jws = jwt.decode()?;
194 let decoded = decode_v2(&jws, &options.additional_typ)?;
195 let time = options.time.pinned();
197 let issuer = &decoded.credential.issuer;
198 let (reference, key) = self
199 .verify(&jws, KeyRole::Issuer, Some(issuer.id().as_str()), time)
200 .await?;
201 check_controller(issuer, &reference, &key, "issuer")?;
202 time.check_claims(&decoded.claims)?;
203 time.check(
204 decoded.credential.valid_from,
205 decoded.credential.valid_until,
206 None,
207 )?;
208 let status = status_claim(&decoded.claims, options.status)?;
209 self.check_status(
210 decoded
211 .credential
212 .statuses()
213 .map(CredentialStatus::Vcdm)
214 .chain(status.iter().map(status_claim_entry))
215 .collect(),
216 options.status,
217 time,
218 )
219 .await?;
220 Ok(decoded)
221 }
222
223 pub(super) async fn verify(
226 &self,
227 jws: &CompactJws,
228 role: KeyRole,
229 iss: Option<&str>,
230 time: TimeOptions,
231 ) -> Result<(KeyReference, Jwk), ValidationError> {
232 let (reference, key) =
233 resolve_jws_key(&self.resolver, jws, iss, role, time.now().timestamp()).await?;
234 jws.verify(&self.verifier, &key)?;
235 Ok((reference, key))
236 }
237
238 pub(super) async fn check_status(
240 &self,
241 statuses: Vec<CredentialStatus<'_>>,
242 policy: StatusPolicy,
243 time: TimeOptions,
244 ) -> Result<(), ValidationError> {
245 check_statuses(self.status.as_deref(), statuses, policy, time).await
246 }
247}
248
249impl<R: core::fmt::Debug, V: core::fmt::Debug> core::fmt::Debug for JwtCredentialValidator<R, V> {
250 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
251 f.debug_struct("JwtCredentialValidator")
252 .field("resolver", &self.resolver)
253 .field("verifier", &self.verifier)
254 .field("status", &self.status.as_ref().map(|_| "StatusCheck"))
255 .finish()
256 }
257}
258
259pub fn decode_credential(jwt: &Jwt) -> Result<DecodedCredential, ValidationError> {
267 decode(&jwt.decode()?, &NO_TYP)
268}
269
270pub fn decode_credential_v2(jwt: &Jwt) -> Result<DecodedCredentialV2, ValidationError> {
276 decode_v2(&jwt.decode()?, &NO_TYP)
277}
278
279pub(super) static NO_TYP: BTreeSet<String> = BTreeSet::new();
281
282pub(super) fn decode(
285 jws: &CompactJws,
286 additional_typ: &BTreeSet<String>,
287) -> Result<DecodedCredential, ValidationError> {
288 check_typ(jws.header(), "JWT", additional_typ)?;
289 let claims = plain_claims(jws)?;
290 let credential = Credential::from_jwt_claims(&claims)?;
291 Ok(DecodedCredential {
292 header: jws.header().clone(),
293 claims,
294 credential,
295 })
296}
297
298pub(super) fn decode_v2(
302 jws: &CompactJws,
303 additional_typ: &BTreeSet<String>,
304) -> Result<DecodedCredentialV2, ValidationError> {
305 check_typ(jws.header(), CredentialV2::JWT_TYP, additional_typ)?;
306 let claims = plain_claims(jws)?;
307 let credential = CredentialV2::from_jwt_claims(&claims)?;
308 Ok(DecodedCredentialV2 {
309 header: jws.header().clone(),
310 claims,
311 credential,
312 })
313}
314
315pub(super) fn plain_claims(jws: &CompactJws) -> Result<JwtClaims, ValidationError> {
318 let claims: JwtClaims =
319 serde_json::from_slice(jws.payload()).map_err(ValidationError::Payload)?;
320 match claims
321 .additional
322 .iter()
323 .find_map(|(name, value)| sd_jwt_member(name, value))
324 {
325 Some(claim) => Err(ValidationError::SdJwtPayload { claim }),
326 None => Ok(claims),
327 }
328}
329
330const SD_JWT_NAMES: [&str; 2] = ["_sd", "_sd_alg"];
333const ELLIPSIS: &str = "...";
334
335fn sd_jwt_member(name: &str, value: &Value) -> Option<&'static str> {
338 SD_JWT_NAMES
339 .into_iter()
340 .find(|reserved| *reserved == name)
341 .or_else(|| sd_jwt_name_in(value))
342}
343
344fn sd_jwt_name_in(value: &Value) -> Option<&'static str> {
346 match value {
347 Value::Object(object) => object
348 .iter()
349 .find_map(|(name, value)| sd_jwt_member(name, value)),
350 Value::Array(array) => array.iter().find_map(|element| match element {
351 Value::Object(object)
352 if object.len() == 1 && object.get(ELLIPSIS).is_some_and(Value::is_string) =>
353 {
354 Some(ELLIPSIS)
355 }
356 element => sd_jwt_name_in(element),
357 }),
358 _ => None,
359 }
360}
361
362pub(super) fn check_typ(
364 header: &JwsHeader,
365 expected: &'static str,
366 additional: &BTreeSet<String>,
367) -> Result<(), ValidationError> {
368 match header.typ.as_deref() {
369 Some(found) if found != expected && !additional.contains(found) => {
370 Err(ValidationError::UnexpectedTyp {
371 expected,
372 found: found.to_owned(),
373 })
374 }
375 _ => Ok(()),
376 }
377}
378
379pub(super) fn check_controller(
382 party: &Party,
383 reference: &KeyReference,
384 key: &Jwk,
385 role: &'static str,
386) -> Result<(), ValidationError> {
387 let id = party.id();
388 if !reference.binds_to(Some(id.as_str()), key) {
389 return Err(mismatch(role, id.clone(), reference.clone()));
390 }
391 Ok(())
392}
393
394fn mismatch(role: &'static str, id: Uri, key: KeyReference) -> ValidationError {
396 if role == "holder" {
397 ValidationError::HolderMismatch {
398 holder: id,
399 key: Box::new(key),
400 }
401 } else {
402 ValidationError::IssuerMismatch {
403 issuer: id,
404 key: Box::new(key),
405 }
406 }
407}