yourevalid

Validation type and trait. For internal use in polyproto-related crates, currently.

Overview

yourevalid provides a type-level guarantee system for validated and verified data through the Valid<T> wrapper type and the Validate trait. This crate is used in sonata and polyproto-rs.

Purpose

Many types in cryptographic and security-sensitive contexts cannot guarantee their own validity. For example, a certificate might be well-formed but expired. yourevalid provides a way to explicitly distinguish between "a value of type T" and "a value of type T that has been verified and validated."

Core Concepts

The Valid<T> Type

Look, it's you! 🏳️‍🌈🏳️‍⚧️❤️

Valid<T> is a wrapper type that signals that the contained type T has been successfully verified and validated. New instances of this type can only be created through the Validate trait, ensuring that the validation logic has been executed.

Defining "Verified and Valid"

Wow, it's you again! 🏳️‍🌈🏳️‍⚧️❤️

• "Verified" means "Verified to be well-formed". A type that is verified must exhibit all the acceptance criteria and none of the rejection criteria according to its specification or documentation.

• "Valid" means that, at a given point in time, one can attest that this specific instance of a type is cryptographically and contextually fit/allowed to make the claims that this instance is making. Most importantly, validity is time-sensitive and has only been attested to for a specific point in time. It must be carefully evaluated whether re-validation is necessary to maintain those guarantees if the instance is used to validate information from a different point in time.

Time-Sensitive Validation

Each Valid<T> instance tracks the exact time at which validation was performed (validated_at()). This is done because validity can change over time (e.g. a certificate can be revoked, or a time-bound credential can expire).

Example Use Case

ID-Certs have a lifetime from not_valid_before to not_valid_after. Additionally, ID-Certs can be manually revoked or invalidated. This means that the well-formedness of an ID-Cert says nothing about whether it is valid at a certain point in time. The Valid<T> type helps establish that the validity of a specific ID-Cert has been verified at a certain point in time.

Usage

Implement the Validate trait on types where validity is not a guaranteed property:

use yourevalid::{Valid, Validate};
use chrono::{DateTime, Utc};

#[derive(Debug)]
struct MyCertificate {
    // data...
}

impl Validate<MyCertificate> for MyCertificate {
    type Error = MyValidationError;
    
    // Use the default validate() implementation and provide
    // your validation logic as a closure/function
}

// Later, validate an instance:
let cert = MyCertificate { /* ... */ };
let valid_cert: Valid<MyCertificate> = MyCertificate::validate(
    Some(&db_pool),
    cert,
    Utc::now(),
    |db, cert, time| {
        // Your validation logic here
        Ok(())
    }
).await?;

// Access the validation timestamp
let validated_at = valid_cert.validated_at();

License

MPL-2.0

🏳️‍⚧️ Trans rights are human rights. Be gay, do crime!