ssi_claims_core/verification/
mod.rs

1//! Claims verification traits.
2//!
3//! This modules defines all the trait taking part in the verification pipeline.
4//!
5//! # Verification pipeline
6//!
7//! The "verification pipeline" is the sequence of steps executed by this
8//! library to go from a set of verifiable claims ([`VerifiableClaims`]) to a
9//! [`ProofValidity`] result.
10//! It is defined as follows:
11//!   - Proof extraction: the claims are separated from the proof using the
12//!     [`ExtractProof`] trait.
13//!   - Proof preparation: the proof is *prepared* to verify the input claims
14//!     using the [`PrepareWith`] trait. This steps computes any information
15//!     derived from the claims and/or proof required for the verification.
16//!     At this point, the claims and prepared proof are stored together in a
17//!     [`Verifiable`](crate::Verifiable) instance, ready for verification.
18//!   - Claims validation: the claims are validated using the [`Validate`]
19//!     trait.
20//!   - Proof validation: the claims verified against the proof using the
21//!     [`ValidateProof`] trait.
22mod claims;
23
24use chrono::{DateTime, Utc};
25pub use claims::*;
26mod proof;
27pub use proof::*;
28mod parameters;
29pub use parameters::*;
30
31/// Verifiable Claims.
32///
33/// Set of claims bundled with a proof.
34pub trait VerifiableClaims {
35    /// Claims type.
36    type Claims;
37
38    /// Proof type.
39    type Proof;
40
41    /// The claims.
42    fn claims(&self) -> &Self::Claims;
43
44    /// The proof.
45    fn proof(&self) -> &Self::Proof;
46
47    /// Validates the claims and proof.
48    ///
49    /// The `params` argument provides all the verification parameters required
50    /// to validate the claims and proof.
51    ///
52    /// # What verification parameters should I use?
53    ///
54    /// It really depends on the claims type `Self::Claims` and proof type
55    /// `Self::Proof`, but the [`VerificationParameters`] type is a good
56    /// starting point that should work most of the time.
57    ///
58    /// # Passing the parameters by reference
59    ///
60    /// If the validation traits are implemented for `P`, they will be
61    /// implemented for `&P` as well. This means the parameters can be passed
62    /// by move *or* by reference.
63    #[allow(async_fn_in_trait)]
64    async fn verify<P>(&self, params: P) -> Result<Verification, ProofValidationError>
65    where
66        Self::Claims: ValidateClaims<P, Self::Proof>,
67        Self::Proof: ValidateProof<P, Self::Claims>,
68    {
69        match self.claims().validate_claims(&params, self.proof()) {
70            Ok(_) => self
71                .proof()
72                .validate_proof(&params, self.claims())
73                .await
74                .map(|r| r.map_err(Invalid::Proof)),
75            Err(e) => {
76                // Claims are not valid on their own.
77                Ok(Err(Invalid::Claims(e)))
78            }
79        }
80    }
81}
82
83/// Proof bundling trait.
84///
85/// Provides a method to bundle the set of claims with a proof.
86pub trait AttachProof<T> {
87    /// Set of claims with a proof.
88    type Attached;
89
90    /// Bundles the given claims with this proof.
91    fn attach_to(self, claims: T) -> Self::Attached;
92}
93
94/// Verification outcome.
95pub type Verification = Result<(), Invalid>;
96
97/// Invalid verifiable claims.
98#[derive(Debug, thiserror::Error, PartialEq)]
99pub enum Invalid {
100    #[error("invalid claims: {0}")]
101    Claims(#[from] InvalidClaims),
102
103    #[error("invalid proof: {0}")]
104    Proof(#[from] InvalidProof),
105}
106
107/// Arbitrary resource provider.
108pub trait ResourceProvider<T> {
109    /// Returns a reference to the resource of type `T`.
110    fn get_resource(&self) -> &T;
111}
112
113/// Anything can return the unit resource.
114impl<T> ResourceProvider<()> for T {
115    fn get_resource(&self) -> &() {
116        &()
117    }
118}
119
120/// Type that provides a public key resolver.
121pub trait ResolverProvider {
122    /// Public key resolver.
123    type Resolver;
124
125    /// Returns a reference to the environment's public key resolver.
126    fn resolver(&self) -> &Self::Resolver;
127}
128
129impl<E: ResolverProvider> ResolverProvider for &E {
130    type Resolver = E::Resolver;
131
132    fn resolver(&self) -> &Self::Resolver {
133        E::resolver(*self)
134    }
135}
136
137/// Type that provides date and time.
138///
139/// Used to check the validity period of given claims.
140pub trait DateTimeProvider {
141    /// Returns the current date and time.
142    fn date_time(&self) -> DateTime<Utc>;
143}
144
145impl<E: DateTimeProvider> DateTimeProvider for &E {
146    fn date_time(&self) -> DateTime<Utc> {
147        E::date_time(*self)
148    }
149}
ssi_claims_core/verification/mod.rs

ssi_claims_core/verification/
mod.rs
