auths_verifier/

types.rs

//! Verification types: reports, statuses, and device DIDs.

use crate::freshness::Freshness;
use crate::witness::WitnessQuorum;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

// ============================================================================
// Verification Report Types
// ============================================================================

/// Machine-readable verification result containing status, chain details, and warnings.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct VerificationReport {
    /// The overall verification status
    pub status: VerificationStatus,
    /// Details of each link in the verification chain
    pub chain: Vec<ChainLink>,
    /// Non-fatal warnings encountered during verification
    pub warnings: Vec<String>,
    /// Optional witness quorum result (present when witness verification was performed)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub witness_quorum: Option<WitnessQuorum>,
    /// Whether the attestation is anchored in a verifiable log: the issuer's
    /// KEL via an ixn seal, or a transparency log via an offline inclusion
    /// proof verified under a pinned log key.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub anchored: Option<auths_keri::AnchorStatus>,
    /// Structured duplicity warning from the shared-KEL detector.
    ///
    /// Fail-closed: a `Some(Diverging { … })` warning makes [`VerificationReport::is_valid`]
    /// return `false` even though `status` still records that the attestation *signature*
    /// verified — a forked KEL is not trustworthy. The structured warning also lets
    /// CLI / iOS / CI render a banner and point the user at `auths device remove` to resolve.
    ///
    /// `None` indicates no divergence was observed (or no shared-KEL
    /// replay was performed).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub duplicity_warning: Option<crate::duplicity::DuplicityReport>,
    /// How fresh this verdict is under the verifier's freshness model (ADR 009). The chain
    /// verifier reads no clock and no network, so an offline verify (no fresher source supplied)
    /// names [`Freshness::Unknown`] — the report is never a bare `Valid` that reads as real-time
    /// fresh. A caller that has a fresher source upgrades it via [`VerificationReport::with_freshness`].
    /// `#[serde(default)]` resolves a missing field to `Unknown` so pre-field JSON still loads.
    #[serde(default)]
    pub freshness: Freshness,
    /// The KEL position this verdict was verified as-of (ADR 009, the `{as_of, freshness}` pair):
    /// the issuer-KEL tip `(seq)` the chain was checked against, when the caller supplies one.
    /// The pure chain verifier reads no KEL tip, so it leaves this `None` ("position unknown") —
    /// honest, never fabricated; a caller holding the slice position stamps it via
    /// [`VerificationReport::with_as_of`]. `#[serde(default)]` keeps pre-field JSON loadable.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub as_of: Option<u128>,
}

impl VerificationReport {
    /// Returns true only when the signature status is `Valid` **and** no duplicity warning is
    /// present. Fail-closed: a valid signature on a KEL that has forked (`Some(Diverging)`) is not
    /// trustworthy, so the trust decision refuses even though `status` records the signature as valid.
    pub fn is_valid(&self) -> bool {
        matches!(self.status, VerificationStatus::Valid) && self.duplicity_warning.is_none()
    }

    /// Creates a new valid VerificationReport with the given chain.
    ///
    /// Freshness defaults to [`Freshness::Unknown`]: the chain verifier consults no fresher
    /// source, so an offline verify is honestly unconfirmable, never silently fresh. A caller
    /// holding a fresher source upgrades it with [`VerificationReport::with_freshness`].
    pub fn valid(chain: Vec<ChainLink>) -> Self {
        Self {
            status: VerificationStatus::Valid,
            chain,
            warnings: Vec::new(),
            witness_quorum: None,
            anchored: None,
            duplicity_warning: None,
            freshness: Freshness::Unknown,
            as_of: None,
        }
    }

    /// Creates a new VerificationReport with the given status and chain.
    ///
    /// Freshness defaults to [`Freshness::Unknown`] (offline, unconfirmable) — see
    /// [`VerificationReport::valid`].
    pub fn with_status(status: VerificationStatus, chain: Vec<ChainLink>) -> Self {
        Self {
            status,
            chain,
            warnings: Vec::new(),
            witness_quorum: None,
            anchored: None,
            duplicity_warning: None,
            freshness: Freshness::Unknown,
            as_of: None,
        }
    }

    /// Attach a duplicity warning to this report. Leaves `status` (the *signature* verdict)
    /// unchanged, but makes [`VerificationReport::is_valid`] fail closed — a diverging shared
    /// KEL is not trustworthy even when the per-attestation signature verified.
    pub fn with_duplicity_warning(mut self, warning: crate::duplicity::DuplicityReport) -> Self {
        self.duplicity_warning = Some(warning);
        self
    }

    /// The freshness this report names (ADR 009). An offline verify is [`Freshness::Unknown`];
    /// a report built with a fresher source carries its classified grade.
    pub fn freshness(&self) -> Freshness {
        self.freshness
    }

    /// Re-stamp this report's freshness from a fresher-source classification.
    ///
    /// The chain verifier itself reads no clock/network, so it always emits `Unknown`. A caller
    /// that holds a fresher source (a witness head, a transparency-log tip) classifies it through
    /// [`crate::freshness::FreshnessPolicy`] and stamps the grade here, so the surfaced verdict
    /// stays honest about what was confirmed.
    ///
    /// Args:
    /// * `freshness`: the classified freshness of this otherwise-valid report.
    pub fn with_freshness(mut self, freshness: Freshness) -> Self {
        self.freshness = freshness;
        self
    }

    /// The KEL position this report was verified as-of (ADR 009), or `None` when the pure chain
    /// verifier was given no slice position to report.
    pub fn as_of(&self) -> Option<u128> {
        self.as_of
    }

    /// Stamp the issuer-KEL slice position this report was verified as-of. Pairs with
    /// [`VerificationReport::with_freshness`]: a caller holding the verified slice records both
    /// *how current* (`as_of`) and *how fresh* (`freshness`) the otherwise-valid report is.
    ///
    /// Args:
    /// * `as_of`: the issuer-KEL tip `(seq)` the chain was verified against.
    pub fn with_as_of(mut self, as_of: u128) -> Self {
        self.as_of = Some(as_of);
        self
    }
}

/// Verification outcome indicating success or the type of failure.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type")]
pub enum VerificationStatus {
    /// The attestation(s) are valid
    Valid,
    /// The attestation has expired
    Expired {
        /// When the attestation expired
        at: DateTime<Utc>,
    },
    /// The attestation has been revoked
    Revoked {
        /// When the attestation was revoked (if known)
        at: Option<DateTime<Utc>>,
    },
    /// A signature in the chain is invalid
    InvalidSignature {
        /// The step in the chain where the invalid signature was found (0-indexed)
        step: usize,
    },
    /// The chain has a broken link (issuer→subject mismatch or missing attestation)
    BrokenChain {
        /// Description of the missing link
        missing_link: String,
    },
    /// Insufficient witness receipts to meet quorum threshold
    InsufficientWitnesses {
        /// Number of witnesses required
        required: usize,
        /// Number of witnesses that verified successfully
        verified: usize,
    },
}

/// A single link in a verification chain, representing one attestation's verification result.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ChainLink {
    /// The issuer DID of this attestation
    pub issuer: String,
    /// The subject DID of this attestation
    pub subject: String,
    /// Whether this link's signature is valid
    pub valid: bool,
    /// Error message if verification failed
    pub error: Option<String>,
}

impl ChainLink {
    /// Creates a new valid chain link.
    pub fn valid(issuer: String, subject: String) -> Self {
        Self {
            issuer,
            subject,
            valid: true,
            error: None,
        }
    }

    /// Creates a new invalid chain link with an error message.
    pub fn invalid(issuer: String, subject: String, error: String) -> Self {
        Self {
            issuer,
            subject,
            valid: false,
            error: Some(error),
        }
    }
}

// ============================================================================
// DID Types
// ============================================================================

use std::borrow::Borrow;
use std::fmt;
use std::ops::Deref;
use std::str::FromStr;

// ============================================================================
// IdentityDID Type
// ============================================================================

/// Strongly-typed wrapper for identity DIDs (e.g., `"did:keri:E..."`).
///
/// Usage:
/// ```rust
/// # use auths_verifier::IdentityDID;
/// let did = IdentityDID::parse("did:keri:Eabc123").unwrap();
/// assert_eq!(did.as_str(), "did:keri:Eabc123");
///
/// let s: String = did.into_inner();
/// ```
#[derive(Debug, Clone, Serialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[repr(transparent)]
pub struct IdentityDID(String);

impl IdentityDID {
    /// Wraps a DID string without validation. Crate-internal only: external callers must use
    /// `parse` / `TryFrom`, which validate the `did:keri:` shape. The clippy ban plus this
    /// visibility make an unvalidated `IdentityDID` unconstructable outside this crate.
    pub(crate) fn new_unchecked<S: Into<String>>(s: S) -> Self {
        Self(s.into())
    }

    /// Validates and parses a `did:keri:` string into an `IdentityDID`.
    ///
    /// Args:
    /// * `s`: A DID string that must start with `did:keri:` followed by a non-empty KERI prefix.
    ///
    /// Usage:
    /// ```rust
    /// # use auths_verifier::IdentityDID;
    /// let did = IdentityDID::parse("did:keri:EPrefix123").unwrap();
    /// assert_eq!(did.as_str(), "did:keri:EPrefix123");
    /// ```
    pub fn parse(s: &str) -> Result<Self, DidParseError> {
        match s.strip_prefix("did:keri:") {
            Some("") => Err(DidParseError::EmptyIdentifier),
            Some(_) => Ok(Self(s.to_string())),
            None => Err(DidParseError::InvalidIdentityPrefix(s.to_string())),
        }
    }

    /// Builds an `IdentityDID` from a raw KERI prefix string.
    ///
    /// Args:
    /// * `prefix`: The KERI prefix without the `did:keri:` scheme (e.g., `"EOrg123"`).
    ///
    /// Usage:
    /// ```rust
    /// # use auths_verifier::IdentityDID;
    /// let did = IdentityDID::from_prefix("EOrg123").unwrap();
    /// assert_eq!(did.as_str(), "did:keri:EOrg123");
    /// ```
    pub fn from_prefix(prefix: &str) -> Result<Self, DidParseError> {
        if prefix.is_empty() {
            return Err(DidParseError::EmptyIdentifier);
        }
        Ok(Self(format!("did:keri:{}", prefix)))
    }

    /// Returns the KERI prefix portion of the DID (after `did:keri:`).
    ///
    /// Usage:
    /// ```rust
    /// # use auths_verifier::IdentityDID;
    /// let did = IdentityDID::parse("did:keri:EOrg123").unwrap();
    /// assert_eq!(did.prefix(), "EOrg123");
    /// ```
    pub fn prefix(&self) -> &str {
        self.0.strip_prefix("did:keri:").unwrap_or(&self.0)
    }

    /// Returns the DID as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Consumes self and returns the inner String.
    pub fn into_inner(self) -> String {
        self.0
    }
}

impl fmt::Display for IdentityDID {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

impl FromStr for IdentityDID {
    type Err = DidParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::parse(s)
    }
}

impl TryFrom<&str> for IdentityDID {
    type Error = DidParseError;

    fn try_from(s: &str) -> Result<Self, Self::Error> {
        Self::parse(s)
    }
}

impl TryFrom<String> for IdentityDID {
    type Error = DidParseError;

    fn try_from(s: String) -> Result<Self, Self::Error> {
        Self::parse(&s)
    }
}

/// Builds an `IdentityDID` from a validated KERI [`Prefix`].
///
/// A `Prefix` may still be empty (the placeholder used during event construction),
/// which is not a legal identity identifier — that one case is rejected as
/// [`DidParseError::EmptyIdentifier`]. Every non-empty prefix yields `did:keri:{prefix}`.
/// This is the single door that replaces hand-built
/// `IdentityDID::new_unchecked(format!("did:keri:{prefix}"))` round-trips.
///
/// Args:
/// * `prefix`: A KERI identity prefix.
///
/// Usage:
/// ```rust
/// # use auths_verifier::IdentityDID;
/// # use auths_keri::Prefix;
/// let prefix = Prefix::new("EOrg123".to_string()).unwrap();
/// let did = IdentityDID::try_from(&prefix).unwrap();
/// assert_eq!(did.as_str(), "did:keri:EOrg123");
/// ```
impl TryFrom<&auths_keri::Prefix> for IdentityDID {
    type Error = DidParseError;

    fn try_from(prefix: &auths_keri::Prefix) -> Result<Self, Self::Error> {
        Self::from_prefix(prefix.as_str())
    }
}

impl TryFrom<auths_keri::Prefix> for IdentityDID {
    type Error = DidParseError;

    fn try_from(prefix: auths_keri::Prefix) -> Result<Self, Self::Error> {
        Self::from_prefix(prefix.as_str())
    }
}

impl From<IdentityDID> for String {
    fn from(did: IdentityDID) -> String {
        did.0
    }
}

impl<'de> serde::Deserialize<'de> for IdentityDID {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        Self::parse(&s).map_err(serde::de::Error::custom)
    }
}

impl Deref for IdentityDID {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl AsRef<str> for IdentityDID {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl Borrow<str> for IdentityDID {
    fn borrow(&self) -> &str {
        &self.0
    }
}

impl PartialEq<str> for IdentityDID {
    fn eq(&self, other: &str) -> bool {
        self.0 == other
    }
}

impl PartialEq<&str> for IdentityDID {
    fn eq(&self, other: &&str) -> bool {
        self.0 == *other
    }
}

impl PartialEq<IdentityDID> for str {
    fn eq(&self, other: &IdentityDID) -> bool {
        self == other.0
    }
}

impl PartialEq<IdentityDID> for &str {
    fn eq(&self, other: &IdentityDID) -> bool {
        *self == other.0
    }
}

impl FromStr for CanonicalDid {
    type Err = DidParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::parse(s)
    }
}

// ============================================================================
// DID Utility Functions
// ============================================================================

/// Convert a hex-encoded Ed25519 public key to a `did:key:` device DID.
///
/// The hex string must decode to exactly 32 bytes.
///
/// ```rust
/// # use auths_verifier::types::signer_hex_to_did;
/// let did = signer_hex_to_did("d75a980182b10ab7d54bfed3c964073a0ee172f3daa3f4a18446b7ddc8").unwrap_err();
/// // (example key is wrong length — a real 32-byte hex key would succeed)
/// ```
pub fn signer_hex_to_did(hex_key: &str) -> Result<CanonicalDid, DidConversionError> {
    signer_hex_to_did_with_curve(hex_key, auths_crypto::CurveType::P256)
}

/// Convert a hex-encoded public key to a `did:key:` device DID with explicit curve.
///
/// ```rust
/// # use auths_verifier::types::signer_hex_to_did_with_curve;
/// # use auths_crypto::CurveType;
/// let did = signer_hex_to_did_with_curve("d75a980182b10ab7d54bfed3c964073a0ee172f3daa3f4a18446b7ddc8", CurveType::P256).unwrap_err();
/// ```
pub fn signer_hex_to_did_with_curve(
    hex_key: &str,
    curve: auths_crypto::CurveType,
) -> Result<CanonicalDid, DidConversionError> {
    let bytes = hex::decode(hex_key).map_err(|e| DidConversionError::InvalidHex(e.to_string()))?;
    let expected = curve.public_key_len();
    if bytes.len() != expected {
        return Err(DidConversionError::WrongKeyLength(bytes.len()));
    }
    Ok(CanonicalDid::from_public_key_did_key(&bytes, curve))
}

/// Validate a DID string (accepts both `did:keri:` and `did:key:` formats).
///
/// Returns `true` if the DID has a recognized scheme and non-empty identifier.
pub fn validate_did(did_str: &str) -> bool {
    if let Some(rest) = did_str.strip_prefix("did:keri:") {
        !rest.is_empty()
    } else if let Some(rest) = did_str.strip_prefix("did:key:") {
        !rest.is_empty()
    } else {
        false
    }
}

/// Errors from DID conversion operations.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum DidConversionError {
    /// The input is not valid hexadecimal.
    #[error("invalid hex: {0}")]
    InvalidHex(String),
    /// The decoded key is not 32 bytes.
    #[error("expected 32-byte Ed25519 key, got {0} bytes")]
    WrongKeyLength(usize),
}

/// Errors from DID string parsing and validation.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum DidParseError {
    /// A `did:key:z…`-shaped DID was required but the prefix didn't match.
    #[error("did:key: DID must start with 'did:key:z', got: {0}")]
    InvalidDevicePrefix(String),
    /// IdentityDID must start with `did:keri:`.
    #[error("IdentityDID must start with 'did:keri:', got: {0}")]
    InvalidIdentityPrefix(String),
    /// The method-specific identifier portion is empty.
    #[error("DID method-specific identifier is empty")]
    EmptyIdentifier,
    /// Generic DID format validation failure (used by `CanonicalDid`).
    #[error("{0}")]
    InvalidFormat(String),
    /// DID string contains control characters.
    #[error("DID contains control characters")]
    ControlCharacters,
}

// ============================================================================
// CanonicalDid Type
// ============================================================================

/// A validated, canonical DID that accepts any method (`did:keri:`, `did:key:`, etc.).
///
/// Use this for fields that can hold either identity or device DIDs,
/// such as attestation issuers which may be `did:keri:` or `did:key:`.
///
/// Constructed via `parse()` which enforces:
/// - Starts with `did:`
/// - Has at least method and id segments: `did:method:id`
/// - Lowercased method (KERI, key methods are case-sensitive in id, not method)
/// - No trailing whitespace or control characters
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[serde(transparent)]
pub struct CanonicalDid(String);

impl CanonicalDid {
    /// Parse and validate a DID string into canonical form.
    pub fn parse(raw: &str) -> Result<Self, DidParseError> {
        if raw.chars().any(|c| c.is_control()) {
            return Err(DidParseError::ControlCharacters);
        }
        let trimmed = raw.trim();
        if trimmed.is_empty() {
            return Err(DidParseError::EmptyIdentifier);
        }
        let parts: Vec<&str> = trimmed.splitn(3, ':').collect();
        if parts.len() < 3 || parts[0] != "did" || parts[1].is_empty() || parts[2].is_empty() {
            return Err(DidParseError::InvalidFormat(format!(
                "invalid DID format: '{}'",
                trimmed
            )));
        }
        let canonical = format!("did:{}:{}", parts[1].to_lowercase(), parts[2]);
        Ok(Self(canonical))
    }

    /// Wraps a DID string without validation (for trusted internal paths).
    pub fn new_unchecked<S: Into<String>>(s: S) -> Self {
        Self(s.into())
    }

    /// Returns the canonical DID as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Returns the method-specific identifier (the part after `did:method:`).
    pub fn method_specific_id(&self) -> &str {
        self.0.splitn(3, ':').nth(2).unwrap_or("")
    }

    /// Returns a sanitized version of the DID for use in Git refs,
    /// replacing all non-alphanumeric characters with `_`.
    pub fn ref_name(&self) -> String {
        self.0
            .chars()
            .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
            .collect()
    }

    /// Compares a sanitized DID ref name to this canonical DID.
    pub fn matches_sanitized_ref(&self, ref_name: &str) -> bool {
        self.ref_name() == ref_name
    }

    /// Tries to reverse-lookup a real DID from a sanitized string,
    /// given a list of known real DIDs.
    pub fn from_sanitized<'a>(sanitized: &str, known_dids: &'a [Self]) -> Option<&'a Self> {
        known_dids.iter().find(|did| did.ref_name() == sanitized)
    }

    /// Construct a `did:key:z…` DID from a raw public key + curve tag.
    ///
    /// Constructs a `did:key:z…` DID from a raw public key + curve
    /// using multicodec varint prefixes.
    ///
    /// Args:
    /// * `pubkey`: 32 bytes (Ed25519) or 33 bytes (P-256 compressed SEC1).
    /// * `curve`: The curve type carried in-band per the wire-format rules.
    ///
    /// Usage:
    /// ```ignore
    /// let did = CanonicalDid::from_public_key_did_key(&bytes, CurveType::P256);
    /// ```
    pub fn from_public_key_did_key(pubkey: &[u8], curve: auths_crypto::CurveType) -> Self {
        let varint: &[u8] = match curve {
            auths_crypto::CurveType::Ed25519 => &[0xED, 0x01],
            auths_crypto::CurveType::P256 => &[0x80, 0x24],
        };
        let mut prefixed = Vec::with_capacity(varint.len() + pubkey.len());
        prefixed.extend_from_slice(varint);
        prefixed.extend_from_slice(pubkey);
        let encoded = bs58::encode(prefixed).into_string();
        Self(format!("did:key:z{}", encoded))
    }

    /// Validates that this DID uses the `keri` method with a valid KERI prefix.
    pub fn require_keri(self) -> Result<Self, DidParseError> {
        let parts: Vec<&str> = self.0.splitn(3, ':').collect();
        if parts[1] != "keri" {
            return Err(DidParseError::InvalidFormat(format!(
                "expected did:keri: DID, got did:{}:",
                parts[1]
            )));
        }
        let id = parts[2];
        if id.len() < 2 || id.len() > 128 {
            return Err(DidParseError::InvalidFormat(
                "invalid KERI prefix: length must be 2–128 characters".into(),
            ));
        }
        if !id.starts_with(|c: char| c.is_ascii_uppercase()) {
            return Err(DidParseError::InvalidFormat(format!(
                "invalid KERI prefix: must start with an uppercase derivation code, got '{}'",
                &id[..1]
            )));
        }
        Ok(self)
    }

    /// Consumes self and returns the inner String.
    pub fn into_inner(self) -> String {
        self.0
    }
}

impl TryFrom<String> for CanonicalDid {
    type Error = DidParseError;
    fn try_from(s: String) -> Result<Self, Self::Error> {
        Self::parse(&s)
    }
}

impl TryFrom<&str> for CanonicalDid {
    type Error = DidParseError;
    fn try_from(s: &str) -> Result<Self, Self::Error> {
        Self::parse(s)
    }
}

impl From<CanonicalDid> for String {
    fn from(d: CanonicalDid) -> Self {
        d.0
    }
}

impl fmt::Display for CanonicalDid {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

impl Deref for CanonicalDid {
    type Target = str;
    fn deref(&self) -> &str {
        &self.0
    }
}

impl AsRef<str> for CanonicalDid {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

impl Borrow<str> for CanonicalDid {
    fn borrow(&self) -> &str {
        &self.0
    }
}

impl<'de> serde::Deserialize<'de> for CanonicalDid {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        Self::parse(&s).map_err(serde::de::Error::custom)
    }
}

impl PartialEq<str> for CanonicalDid {
    fn eq(&self, other: &str) -> bool {
        self.0 == other
    }
}

impl PartialEq<&str> for CanonicalDid {
    fn eq(&self, other: &&str) -> bool {
        self.0 == *other
    }
}

impl From<IdentityDID> for CanonicalDid {
    fn from(did: IdentityDID) -> Self {
        Self(did.into_inner())
    }
}

// ============================================================================
// AssuranceLevel Type
// ============================================================================

/// Cryptographic assurance level of a platform identity claim.
///
/// Variants are ordered from weakest to strongest so that `Ord` comparisons
/// reflect trust strength: `SelfAsserted < TokenVerified < Authenticated < Sovereign`.
///
/// Usage:
/// ```rust
/// # use auths_verifier::types::AssuranceLevel;
/// assert!(AssuranceLevel::Sovereign > AssuranceLevel::Authenticated);
/// assert!(AssuranceLevel::SelfAsserted < AssuranceLevel::TokenVerified);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum AssuranceLevel {
    /// Self-reported identity, signed only by the claimant's own key (e.g., PyPI).
    SelfAsserted,
    /// Bearer token validated against a platform API at time of claim (e.g., npm).
    TokenVerified,
    /// OAuth/OIDC challenge-response proving account control (e.g., GitHub).
    Authenticated,
    /// End-to-end cryptographic identity chain with no third-party trust (auths native).
    Sovereign,
}

/// Error returned when parsing an `AssuranceLevel` from a string fails.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error(
    "invalid assurance level '{0}': expected one of: sovereign, authenticated, token_verified, self_asserted"
)]
pub struct AssuranceLevelParseError(pub String);

impl AssuranceLevel {
    /// Human-readable label for display.
    pub fn label(&self) -> &'static str {
        match self {
            Self::SelfAsserted => "Self-Asserted",
            Self::TokenVerified => "Token-Verified",
            Self::Authenticated => "Authenticated",
            Self::Sovereign => "Sovereign",
        }
    }

    /// Numeric score (1–4) for the assurance level.
    pub fn score(&self) -> u8 {
        match self {
            Self::SelfAsserted => 1,
            Self::TokenVerified => 2,
            Self::Authenticated => 3,
            Self::Sovereign => 4,
        }
    }
}

impl fmt::Display for AssuranceLevel {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.label())
    }
}

impl FromStr for AssuranceLevel {
    type Err = AssuranceLevelParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.trim().to_lowercase().as_str() {
            "sovereign" => Ok(Self::Sovereign),
            "authenticated" => Ok(Self::Authenticated),
            "token_verified" => Ok(Self::TokenVerified),
            "self_asserted" => Ok(Self::SelfAsserted),
            _ => Err(AssuranceLevelParseError(s.to_string())),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use auths_keri::{Prefix, Said};

    #[test]
    fn identity_did_from_validated_prefix() {
        let prefix = Prefix::new_unchecked("EOrg123".to_string());
        let did = IdentityDID::try_from(&prefix).expect("non-empty prefix converts");
        assert_eq!(did.as_str(), "did:keri:EOrg123");
    }

    #[test]
    fn identity_did_try_from_rejects_empty_prefix() {
        let empty = Prefix::default();
        assert!(matches!(
            IdentityDID::try_from(&empty),
            Err(DidParseError::EmptyIdentifier)
        ));
    }

    #[test]
    fn report_without_witness_quorum_deserializes() {
        // JSON from before witness_quorum field existed
        let json = r#"{
            "status": {"type": "Valid"},
            "chain": [],
            "warnings": []
        }"#;
        let report: VerificationReport = serde_json::from_str(json).unwrap();
        assert!(report.is_valid());
        assert!(report.witness_quorum.is_none());
    }

    #[test]
    fn insufficient_witnesses_serializes_correctly() {
        let status = VerificationStatus::InsufficientWitnesses {
            required: 3,
            verified: 1,
        };
        let json = serde_json::to_string(&status).unwrap();
        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed["type"], "InsufficientWitnesses");
        assert_eq!(parsed["required"], 3);
        assert_eq!(parsed["verified"], 1);

        // Roundtrip
        let roundtripped: VerificationStatus = serde_json::from_str(&json).unwrap();
        assert_eq!(roundtripped, status);
    }

    #[test]
    fn report_with_witness_quorum_roundtrips() {
        use crate::witness::{WitnessQuorum, WitnessReceiptResult};

        let report = VerificationReport {
            status: VerificationStatus::Valid,
            chain: vec![],
            warnings: vec![],
            witness_quorum: Some(WitnessQuorum {
                required: 2,
                verified: 2,
                receipts: vec![
                    WitnessReceiptResult {
                        witness_id: "did:key:w1".into(),
                        receipt_said: Said::new_unchecked("EReceipt1".into()),
                        verified: true,
                    },
                    WitnessReceiptResult {
                        witness_id: "did:key:w2".into(),
                        receipt_said: Said::new_unchecked("EReceipt2".into()),
                        verified: true,
                    },
                ],
            }),
            anchored: None,
            duplicity_warning: None,
            freshness: Freshness::Unknown,
            as_of: None,
        };

        let json = serde_json::to_string(&report).unwrap();
        let parsed: VerificationReport = serde_json::from_str(&json).unwrap();
        assert_eq!(report, parsed);
        assert!(parsed.witness_quorum.is_some());
        assert_eq!(parsed.witness_quorum.unwrap().verified, 2);
    }

    #[test]
    fn pre_freshness_report_json_loads_as_unknown() {
        // A report JSON written before the freshness field existed must still deserialize,
        // defaulting freshness to the honest `Unknown` (never a fabricated `Fresh`).
        let json = r#"{"status":{"type":"Valid"},"chain":[],"warnings":[]}"#;
        let report: VerificationReport = serde_json::from_str(json).unwrap();
        assert!(report.is_valid());
        assert_eq!(report.freshness(), Freshness::Unknown);
    }

    #[test]
    fn report_without_witness_quorum_skips_in_json() {
        let report = VerificationReport::valid(vec![]);
        let json = serde_json::to_string(&report).unwrap();
        // witness_quorum should be omitted from JSON when None
        assert!(!json.contains("witness_quorum"));
    }

    // ── AssuranceLevel Tests ──────────────────────────────────────────

    #[test]
    fn assurance_level_ordering() {
        assert!(AssuranceLevel::SelfAsserted < AssuranceLevel::TokenVerified);
        assert!(AssuranceLevel::TokenVerified < AssuranceLevel::Authenticated);
        assert!(AssuranceLevel::Authenticated < AssuranceLevel::Sovereign);
    }

    #[test]
    fn assurance_level_serde_roundtrip() {
        let variants = [
            AssuranceLevel::SelfAsserted,
            AssuranceLevel::TokenVerified,
            AssuranceLevel::Authenticated,
            AssuranceLevel::Sovereign,
        ];
        for level in variants {
            let json = serde_json::to_string(&level).unwrap();
            let parsed: AssuranceLevel = serde_json::from_str(&json).unwrap();
            assert_eq!(parsed, level);
        }
    }

    #[test]
    fn assurance_level_serde_snake_case() {
        assert_eq!(
            serde_json::to_string(&AssuranceLevel::SelfAsserted).unwrap(),
            "\"self_asserted\""
        );
        assert_eq!(
            serde_json::to_string(&AssuranceLevel::TokenVerified).unwrap(),
            "\"token_verified\""
        );
        assert_eq!(
            serde_json::to_string(&AssuranceLevel::Authenticated).unwrap(),
            "\"authenticated\""
        );
        assert_eq!(
            serde_json::to_string(&AssuranceLevel::Sovereign).unwrap(),
            "\"sovereign\""
        );
    }

    #[test]
    fn assurance_level_from_str() {
        assert_eq!(
            "sovereign".parse::<AssuranceLevel>().unwrap(),
            AssuranceLevel::Sovereign
        );
        assert_eq!(
            "authenticated".parse::<AssuranceLevel>().unwrap(),
            AssuranceLevel::Authenticated
        );
        assert_eq!(
            "token_verified".parse::<AssuranceLevel>().unwrap(),
            AssuranceLevel::TokenVerified
        );
        assert_eq!(
            "self_asserted".parse::<AssuranceLevel>().unwrap(),
            AssuranceLevel::SelfAsserted
        );
        assert!("invalid".parse::<AssuranceLevel>().is_err());
    }

    #[test]
    fn assurance_level_from_str_case_insensitive() {
        assert_eq!(
            "SOVEREIGN".parse::<AssuranceLevel>().unwrap(),
            AssuranceLevel::Sovereign
        );
        assert_eq!(
            "Authenticated".parse::<AssuranceLevel>().unwrap(),
            AssuranceLevel::Authenticated
        );
    }

    #[test]
    fn assurance_level_score() {
        assert_eq!(AssuranceLevel::SelfAsserted.score(), 1);
        assert_eq!(AssuranceLevel::TokenVerified.score(), 2);
        assert_eq!(AssuranceLevel::Authenticated.score(), 3);
        assert_eq!(AssuranceLevel::Sovereign.score(), 4);
    }

    #[test]
    fn assurance_level_display() {
        assert_eq!(AssuranceLevel::SelfAsserted.to_string(), "Self-Asserted");
        assert_eq!(AssuranceLevel::TokenVerified.to_string(), "Token-Verified");
        assert_eq!(AssuranceLevel::Authenticated.to_string(), "Authenticated");
        assert_eq!(AssuranceLevel::Sovereign.to_string(), "Sovereign");
    }
}