baseid_pctf/

assurance.rs

//! Identity assurance level evaluation per PCTF Verified Person component.
//!
//! Maps identity-proofing evidence to PCTF Levels 1-3 using the DIACC
//! evidence taxonomy. Also supports cross-framework mapping to eIDAS,
//! NIST 800-63, and TDIF via `baseid_core::types::AssuranceLevel`.

use baseid_core::types::AssuranceLevel;
use serde::{Deserialize, Serialize};

/// Types of identity-proofing evidence per PCTF evidence taxonomy.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum EvidenceType {
    /// Self-asserted information (name, address, etc.).
    SelfAsserted,
    /// Knowledge-based verification (security questions, shared secrets).
    KnowledgeBased,
    /// Email or phone verification (OTP, magic link).
    ChannelBinding,
    /// Government-issued photo ID (passport, driver's licence, PR card).
    GovernmentPhotoId,
    /// Government-issued non-photo document (SIN letter, birth certificate).
    GovernmentDocument,
    /// Utility bill, bank statement, or similar address document.
    AddressDocument,
    /// Automated document verification (OCR + liveness + database check).
    DocumentVerification,
    /// Biometric capture (facial recognition, fingerprint).
    Biometric,
    /// In-person identity proofing at a trusted location.
    InPerson,
    /// Supervised remote identity proofing (video call with agent).
    SupervisedRemote,
    /// Credential from a trusted issuer (e.g., bank KYC, provincial ID program).
    TrustedCredential,
}

/// Verification method used to validate evidence.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum VerificationMethod {
    /// No verification beyond possession.
    Unverified,
    /// Checked against an authoritative database.
    DatabaseCheck,
    /// Visual inspection by a human operator.
    VisualInspection,
    /// Automated document authenticity check (OCR, hologram, MRZ).
    AutomatedCheck,
    /// Biometric comparison against reference (1:1 match).
    BiometricMatch,
    /// Cryptographic proof (digital signature verification).
    CryptographicProof,
}

/// A single piece of identity-proofing evidence with metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Evidence {
    /// Type of evidence.
    pub evidence_type: EvidenceType,
    /// How the evidence was verified.
    pub verification: VerificationMethod,
    /// Who issued or verified this evidence (DID or identifier).
    pub issuer: String,
    /// When the evidence was collected (RFC 3339).
    pub timestamp: String,
}

/// A bundle of evidence submitted for assurance level evaluation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvidenceBundle {
    /// The subject being evaluated (holder DID).
    pub subject: String,
    /// Evidence items.
    pub evidence: Vec<Evidence>,
}

/// Result of an assurance level evaluation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvaluationResult {
    /// The determined assurance level.
    pub level: AssuranceLevel,
    /// PCTF level name (e.g., "Level 2").
    pub pctf_name: String,
    /// Reasoning for the determined level.
    pub reasoning: Vec<String>,
    /// Whether the evidence meets requirements for the next level up.
    pub upgrade_possible: bool,
    /// What additional evidence would be needed to reach the next level.
    pub upgrade_requirements: Vec<String>,
}

/// Evaluates identity assurance levels per PCTF Verified Person component.
///
/// # Scoring rules
///
/// - **Level 1** (Low): Self-asserted identity or unverified evidence only.
/// - **Level 2** (Substantial): At least one verified government document
///   plus one additional verification factor (channel binding, knowledge-based,
///   or document verification).
/// - **Level 3** (High): In-person or supervised remote proofing, plus
///   biometric capture, plus verified government photo ID.
pub struct AssuranceLevelEvaluator;

impl AssuranceLevelEvaluator {
    /// Evaluate assurance level from a legacy string-based evidence list.
    ///
    /// This is the original API. For richer evaluation, use `evaluate_bundle`.
    pub fn evaluate(evidence: &[&str]) -> AssuranceLevel {
        // Map string evidence to typed evidence for evaluation.
        let has = |keyword: &str| evidence.iter().any(|e| e.contains(keyword));

        let has_biometric = has("biometric") || has("facial") || has("fingerprint");
        let has_in_person = has("in-person") || has("in_person") || has("supervised");
        let has_govt_photo = has("passport")
            || has("driver")
            || has("photo_id")
            || has("photo-id")
            || has("government_photo");
        let has_govt_doc = has_govt_photo || has("birth") || has("sin") || has("government");
        let has_verification = has("verification")
            || has("database")
            || has("automated")
            || has("ocr")
            || has("verified");
        let has_additional = has("email")
            || has("phone")
            || has("otp")
            || has("knowledge")
            || has("channel")
            || has_verification;

        // Level 3: in-person/supervised + biometric + government photo ID
        if (has_in_person) && has_biometric && has_govt_photo {
            return AssuranceLevel::High;
        }

        // Level 2: verified government document + additional factor
        if has_govt_doc && has_additional {
            return AssuranceLevel::Substantial;
        }

        // Level 1: everything else
        AssuranceLevel::Low
    }

    /// Evaluate assurance level from a structured evidence bundle.
    pub fn evaluate_bundle(bundle: &EvidenceBundle) -> EvaluationResult {
        let evidence = &bundle.evidence;
        let mut reasoning = Vec::new();

        // Check for Level 3 requirements
        let has_in_person = evidence.iter().any(|e| {
            matches!(
                e.evidence_type,
                EvidenceType::InPerson | EvidenceType::SupervisedRemote
            )
        });
        let has_biometric = evidence.iter().any(|e| {
            e.evidence_type == EvidenceType::Biometric
                && matches!(
                    e.verification,
                    VerificationMethod::BiometricMatch | VerificationMethod::AutomatedCheck
                )
        });
        let has_govt_photo_verified = evidence.iter().any(|e| {
            e.evidence_type == EvidenceType::GovernmentPhotoId
                && !matches!(e.verification, VerificationMethod::Unverified)
        });
        let has_govt_doc = evidence.iter().any(|e| {
            matches!(
                e.evidence_type,
                EvidenceType::GovernmentPhotoId | EvidenceType::GovernmentDocument
            ) && !matches!(e.verification, VerificationMethod::Unverified)
        });
        let has_additional_factor = evidence.iter().any(|e| {
            matches!(
                e.evidence_type,
                EvidenceType::ChannelBinding
                    | EvidenceType::KnowledgeBased
                    | EvidenceType::DocumentVerification
                    | EvidenceType::TrustedCredential
            )
        });

        // Level 3
        if has_in_person && has_biometric && has_govt_photo_verified {
            reasoning.push("In-person or supervised remote proofing confirmed".to_string());
            reasoning.push("Biometric capture with match verification".to_string());
            reasoning.push("Verified government photo ID presented".to_string());
            return EvaluationResult {
                level: AssuranceLevel::High,
                pctf_name: AssuranceLevel::High.pctf_name().to_string(),
                reasoning,
                upgrade_possible: false,
                upgrade_requirements: vec![],
            };
        }

        // Level 2
        if has_govt_doc && has_additional_factor {
            reasoning.push("Verified government document confirmed".to_string());
            reasoning.push("Additional verification factor present".to_string());

            let mut upgrade_reqs = Vec::new();
            if !has_in_person {
                upgrade_reqs.push("In-person or supervised remote proofing".to_string());
            }
            if !has_biometric {
                upgrade_reqs.push("Biometric capture with match verification".to_string());
            }
            if !has_govt_photo_verified {
                upgrade_reqs.push("Verified government photo ID".to_string());
            }

            return EvaluationResult {
                level: AssuranceLevel::Substantial,
                pctf_name: AssuranceLevel::Substantial.pctf_name().to_string(),
                reasoning,
                upgrade_possible: true,
                upgrade_requirements: upgrade_reqs,
            };
        }

        // Level 1
        if evidence.is_empty() {
            reasoning.push("No evidence provided".to_string());
        } else {
            reasoning.push("Evidence does not meet Level 2 requirements".to_string());
        }

        let mut upgrade_reqs =
            vec!["Verified government document (photo ID or official document)".to_string()];
        if !has_additional_factor {
            upgrade_reqs.push(
                "Additional factor (channel binding, knowledge-based, or document verification)"
                    .to_string(),
            );
        }

        EvaluationResult {
            level: AssuranceLevel::Low,
            pctf_name: AssuranceLevel::Low.pctf_name().to_string(),
            reasoning,
            upgrade_possible: true,
            upgrade_requirements: upgrade_reqs,
        }
    }
}

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

    #[test]
    fn level1_no_evidence() {
        assert_eq!(AssuranceLevelEvaluator::evaluate(&[]), AssuranceLevel::Low);
    }

    #[test]
    fn level1_self_asserted_only() {
        assert_eq!(
            AssuranceLevelEvaluator::evaluate(&["self-asserted name", "self-asserted email"]),
            AssuranceLevel::Low
        );
    }

    #[test]
    fn level2_govt_doc_plus_verification() {
        assert_eq!(
            AssuranceLevelEvaluator::evaluate(&["government_id", "email verified"]),
            AssuranceLevel::Substantial
        );
    }

    #[test]
    fn level2_passport_plus_phone() {
        assert_eq!(
            AssuranceLevelEvaluator::evaluate(&["passport", "phone otp"]),
            AssuranceLevel::Substantial
        );
    }

    #[test]
    fn level3_in_person_biometric_photo_id() {
        assert_eq!(
            AssuranceLevelEvaluator::evaluate(&["in-person", "biometric", "passport"]),
            AssuranceLevel::High
        );
    }

    #[test]
    fn level3_supervised_remote() {
        assert_eq!(
            AssuranceLevelEvaluator::evaluate(&[
                "supervised video",
                "facial biometric",
                "driver photo_id"
            ]),
            AssuranceLevel::High
        );
    }

    #[test]
    fn bundle_level1_empty() {
        let bundle = EvidenceBundle {
            subject: "did:key:z6MkTest".to_string(),
            evidence: vec![],
        };
        let result = AssuranceLevelEvaluator::evaluate_bundle(&bundle);
        assert_eq!(result.level, AssuranceLevel::Low);
        assert_eq!(result.pctf_name, "Level 1");
        assert!(result.upgrade_possible);
        assert!(!result.upgrade_requirements.is_empty());
    }

    #[test]
    fn bundle_level1_self_asserted() {
        let bundle = EvidenceBundle {
            subject: "did:key:z6MkTest".to_string(),
            evidence: vec![Evidence {
                evidence_type: EvidenceType::SelfAsserted,
                verification: VerificationMethod::Unverified,
                issuer: "self".to_string(),
                timestamp: "2026-01-01T00:00:00Z".to_string(),
            }],
        };
        let result = AssuranceLevelEvaluator::evaluate_bundle(&bundle);
        assert_eq!(result.level, AssuranceLevel::Low);
    }

    #[test]
    fn bundle_level2_govt_doc_plus_channel() {
        let bundle = EvidenceBundle {
            subject: "did:key:z6MkTest".to_string(),
            evidence: vec![
                Evidence {
                    evidence_type: EvidenceType::GovernmentDocument,
                    verification: VerificationMethod::DatabaseCheck,
                    issuer: "did:web:gov.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
                Evidence {
                    evidence_type: EvidenceType::ChannelBinding,
                    verification: VerificationMethod::AutomatedCheck,
                    issuer: "did:web:verify.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
            ],
        };
        let result = AssuranceLevelEvaluator::evaluate_bundle(&bundle);
        assert_eq!(result.level, AssuranceLevel::Substantial);
        assert_eq!(result.pctf_name, "Level 2");
        assert!(result.upgrade_possible);
    }

    #[test]
    fn bundle_level3_full_proofing() {
        let bundle = EvidenceBundle {
            subject: "did:key:z6MkTest".to_string(),
            evidence: vec![
                Evidence {
                    evidence_type: EvidenceType::InPerson,
                    verification: VerificationMethod::VisualInspection,
                    issuer: "did:web:servicecanada.gc.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
                Evidence {
                    evidence_type: EvidenceType::Biometric,
                    verification: VerificationMethod::BiometricMatch,
                    issuer: "did:web:servicecanada.gc.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
                Evidence {
                    evidence_type: EvidenceType::GovernmentPhotoId,
                    verification: VerificationMethod::DatabaseCheck,
                    issuer: "did:web:servicecanada.gc.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
            ],
        };
        let result = AssuranceLevelEvaluator::evaluate_bundle(&bundle);
        assert_eq!(result.level, AssuranceLevel::High);
        assert_eq!(result.pctf_name, "Level 3");
        assert!(!result.upgrade_possible);
    }

    #[test]
    fn bundle_level2_upgrade_requirements() {
        let bundle = EvidenceBundle {
            subject: "did:key:z6MkTest".to_string(),
            evidence: vec![
                Evidence {
                    evidence_type: EvidenceType::GovernmentPhotoId,
                    verification: VerificationMethod::VisualInspection,
                    issuer: "did:web:gov.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
                Evidence {
                    evidence_type: EvidenceType::DocumentVerification,
                    verification: VerificationMethod::AutomatedCheck,
                    issuer: "did:web:verify.ca".to_string(),
                    timestamp: "2026-01-01T00:00:00Z".to_string(),
                },
            ],
        };
        let result = AssuranceLevelEvaluator::evaluate_bundle(&bundle);
        assert_eq!(result.level, AssuranceLevel::Substantial);
        // Should need in-person and biometric for Level 3
        assert!(result
            .upgrade_requirements
            .iter()
            .any(|r| r.contains("In-person")));
        assert!(result
            .upgrade_requirements
            .iter()
            .any(|r| r.contains("Biometric")));
    }

    #[test]
    fn evidence_type_serde_roundtrip() {
        let evidence = Evidence {
            evidence_type: EvidenceType::GovernmentPhotoId,
            verification: VerificationMethod::DatabaseCheck,
            issuer: "did:web:gov.ca".to_string(),
            timestamp: "2026-01-01T00:00:00Z".to_string(),
        };
        let json = serde_json::to_string(&evidence).unwrap();
        let back: Evidence = serde_json::from_str(&json).unwrap();
        assert_eq!(back.evidence_type, EvidenceType::GovernmentPhotoId);
        assert_eq!(back.verification, VerificationMethod::DatabaseCheck);
    }
}