baseid_core/

lifecycle.rs

//! Unified credential lifecycle traits.
//!
//! These traits define the common operations across all credential formats:
//! issuance, verification, and presentation. Each format crate (baseid-vc,
//! baseid-sd-jwt, baseid-mdl, baseid-bbs) provides its own implementation.
//!
//! The trait design is forward-compatible with zero-knowledge proofs:
//! `DisclosureSelection` supports predicates from day one, even though
//! only BBS+ and AnonCreds implementations will support them. Formats
//! that don't support predicates return `Err(UnsupportedPredicate)`.

use serde::{Deserialize, Serialize};

use crate::claims::{ClaimPath, ClaimSet, DisclosureSelection, PredicateType};
use crate::types::{CredentialFormat, DateTime, Uri};

/// Options controlling credential issuance.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct IssuanceOptions {
    /// Credential identifier (URI).
    pub credential_id: Option<String>,
    /// Credential type(s) beyond the base type.
    pub types: Vec<String>,
    /// Validity start time (RFC 3339). Defaults to now if not set.
    pub valid_from: Option<DateTime>,
    /// Expiration time (RFC 3339).
    pub valid_until: Option<DateTime>,
    /// Credential status endpoint for revocation.
    pub status: Option<serde_json::Value>,
}

/// An issued credential in its serialized format.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IssuedCredential {
    /// The serialized credential bytes (JWT string, CBOR bytes, etc.).
    pub data: Vec<u8>,
    /// The credential format.
    pub format: CredentialFormat,
    /// Credential identifier, if assigned.
    pub id: Option<String>,
    /// Issuer DID.
    pub issuer: Uri,
    /// Subject DID, if bound to a holder.
    pub subject: Option<Uri>,
}

/// Options controlling credential presentation.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PresentationOptions {
    /// Verifier-provided nonce for freshness.
    pub nonce: Option<String>,
    /// Intended audience (verifier DID or URL).
    pub audience: Option<String>,
    /// Holder DID (for key binding).
    pub holder_did: Option<String>,
}

/// A credential presentation ready to be sent to a verifier.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PresentedCredential {
    /// The serialized presentation bytes.
    pub data: Vec<u8>,
    /// The credential format.
    pub format: CredentialFormat,
    /// Whether this presentation is unlinkable (true for BBS+ derived proofs).
    pub unlinkable: bool,
}

/// Status of revocation checking for a credential.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum RevocationStatus {
    /// Revocation was not checked (no status mechanism configured).
    NotChecked,
    /// Revocation was checked and the credential is valid (not revoked).
    Valid,
    /// The credential has been revoked.
    Revoked,
    /// Revocation check failed (e.g., status endpoint unreachable).
    CheckFailed,
}

/// The outcome of credential verification.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VerificationOutcome {
    /// Whether the credential signature is valid.
    pub valid: bool,
    /// The credential format that was verified.
    pub format: CredentialFormat,
    /// Issuer DID extracted from the credential.
    pub issuer: Uri,
    /// Subject DID, if present.
    pub subject: Option<Uri>,
    /// The disclosed claims.
    pub claims: ClaimSet,
    /// Whether the presentation provides unlinkability (BBS+ derived proofs).
    pub unlinkable: bool,
    /// Predicates that were verified (only for ZK-capable formats).
    pub predicates_verified: Vec<(ClaimPath, PredicateType)>,
    /// Credential expiration, if present.
    pub valid_until: Option<DateTime>,
    /// Revocation status of the credential.
    pub revocation_status: RevocationStatus,
}

/// Trait for issuing credentials in a specific format.
///
/// Implementors: `SdJwtLifecycle`, `VcJwtLifecycle`, `MdocLifecycle`, `BbsLifecycle`.
pub trait CredentialIssuer: Send + Sync {
    /// The credential format produced by this issuer.
    fn format(&self) -> CredentialFormat;

    /// Issue a credential.
    ///
    /// # Arguments
    /// * `issuer_did` - The DID of the issuer
    /// * `subject_did` - The DID of the subject (holder), if holder-bound
    /// * `claims` - The claims to include in the credential
    /// * `options` - Additional issuance options (types, validity, status)
    fn issue(
        &self,
        issuer_did: &str,
        subject_did: Option<&str>,
        claims: &ClaimSet,
        options: &IssuanceOptions,
    ) -> crate::Result<IssuedCredential>;
}

/// Trait for verifying credentials in a specific format.
pub trait CredentialVerifier: Send + Sync {
    /// The credential format this verifier handles.
    fn format(&self) -> CredentialFormat;

    /// Verify a credential and return the verification outcome.
    ///
    /// # Arguments
    /// * `credential_data` - The serialized credential bytes
    fn verify(&self, credential_data: &[u8]) -> crate::Result<VerificationOutcome>;
}

/// Trait for creating credential presentations with selective disclosure.
pub trait CredentialPresenter: Send + Sync {
    /// The credential format this presenter handles.
    fn format(&self) -> CredentialFormat;

    /// Create a presentation from a credential with selective disclosure.
    ///
    /// Formats that don't support predicates (SD-JWT, JWT-VC, mdoc) must
    /// return `Err(CredentialError::UnsupportedPredicate)` if the disclosure
    /// selection contains any `ClaimDisclosure::Predicate` entries.
    ///
    /// # Arguments
    /// * `credential_data` - The serialized credential bytes
    /// * `disclosure` - Which claims to reveal, hide, or prove predicates about
    /// * `options` - Presentation options (nonce, audience, holder DID)
    fn present(
        &self,
        credential_data: &[u8],
        disclosure: &DisclosureSelection,
        options: &PresentationOptions,
    ) -> crate::Result<PresentedCredential>;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn issuance_options_defaults() {
        let opts = IssuanceOptions::default();
        assert!(opts.credential_id.is_none());
        assert!(opts.types.is_empty());
        assert!(opts.valid_from.is_none());
        assert!(opts.valid_until.is_none());
        assert!(opts.status.is_none());
    }

    #[test]
    fn presentation_options_defaults() {
        let opts = PresentationOptions::default();
        assert!(opts.nonce.is_none());
        assert!(opts.audience.is_none());
        assert!(opts.holder_did.is_none());
    }

    #[test]
    fn issued_credential_serializes() {
        let cred = IssuedCredential {
            data: b"test-jwt".to_vec(),
            format: CredentialFormat::SdJwtVc,
            id: Some("urn:uuid:1234".to_string()),
            issuer: "did:key:issuer".to_string(),
            subject: Some("did:key:holder".to_string()),
        };
        let json = serde_json::to_string(&cred).unwrap();
        let decoded: IssuedCredential = serde_json::from_str(&json).unwrap();
        assert_eq!(decoded.format, CredentialFormat::SdJwtVc);
        assert_eq!(decoded.issuer, "did:key:issuer");
    }

    #[test]
    fn verification_outcome_serializes() {
        let outcome = VerificationOutcome {
            valid: true,
            format: CredentialFormat::W3cVc,
            issuer: "did:key:issuer".to_string(),
            subject: Some("did:key:holder".to_string()),
            claims: ClaimSet::new(),
            unlinkable: false,
            predicates_verified: vec![],
            valid_until: None,
            revocation_status: RevocationStatus::NotChecked,
        };
        let json = serde_json::to_string(&outcome).unwrap();
        let decoded: VerificationOutcome = serde_json::from_str(&json).unwrap();
        assert!(decoded.valid);
        assert!(!decoded.unlinkable);
    }
}