entropy-auth 2026.7.31

//! Have I Been Pwned (HIBP) k-anonymity password breach checking.
//!
//! This module is **transport-agnostic**: it computes the SHA-1 hash and
//! prefix needed for the HIBP range API, and parses the response body.
//! The caller is responsible for making the HTTP request to
//! `https://api.pwnedpasswords.com/range/{prefix}`.
//!
//! # Protocol
//!
//! The HIBP Pwned Passwords API uses k-anonymity to avoid sending the
//! full password hash over the network:
//!
//! 1. SHA-1 hash the password, uppercase hex-encode it (40 characters).
//! 2. Send the first 5 characters (the *prefix*) to the API.
//! 3. The API returns all known suffix/count pairs for that prefix.
//! 4. Check locally whether the remaining 35-character suffix appears in
//!    the response.
//!
//! # Example
//!
//! ```
//! use entropy_auth::mfa::hibp::{HibpPrefix, HibpResponse};
//!
//! let prefix = HibpPrefix::from_password("password");
//! assert_eq!(prefix.as_str(), "5BAA6");
//!
//! // In a real application, you would HTTP GET:
//! //   https://api.pwnedpasswords.com/range/{prefix.as_str()}
//! // and pass the response body to HibpResponse::parse().
//! ```

use core::fmt;

use crate::crypto::Sha1;
use crate::crypto::constant_time::constant_time_eq;
use crate::encoding::hex_encode_upper;

// ---------------------------------------------------------------------------
// SHA-1 hex helper
// ---------------------------------------------------------------------------

/// Compute the SHA-1 hash of a password and return it as an uppercase
/// 40-character hexadecimal string.
///
/// This is the format expected by the HIBP Pwned Passwords API.
#[must_use]
pub fn hibp_sha1_hex(password: &str) -> String {
    let digest = Sha1::digest(password.as_bytes());
    hex_encode_upper(&digest)
}

// ---------------------------------------------------------------------------
// HibpPrefix
// ---------------------------------------------------------------------------

/// The 5-character prefix and full hash for a HIBP k-anonymity lookup.
///
/// Constructed from a password via [`from_password`](HibpPrefix::from_password).
/// The prefix is sent to the HIBP range API, while the suffix is used
/// locally to check the response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HibpPrefix {
    hash: String,
}

impl HibpPrefix {
    /// Computes the SHA-1 hash of `password` and stores the uppercase
    /// hex result for prefix/suffix splitting.
    #[must_use]
    pub fn from_password(password: &str) -> Self {
        Self {
            hash: hibp_sha1_hex(password),
        }
    }

    /// Returns the 5-character prefix to send to the HIBP range API.
    #[must_use]
    #[inline]
    pub fn as_str(&self) -> &str {
        &self.hash[..5]
    }

    /// Returns the 35-character suffix used for local comparison against
    /// the API response.
    #[must_use]
    #[inline]
    pub fn suffix(&self) -> &str {
        &self.hash[5..]
    }

    /// Returns the full 40-character uppercase hex SHA-1 hash.
    #[must_use]
    #[inline]
    pub fn full_hash(&self) -> &str {
        &self.hash
    }
}

// ---------------------------------------------------------------------------
// BreachResult
// ---------------------------------------------------------------------------

/// The result of checking a password against the HIBP response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BreachResult {
    /// The password was not found in the breach database.
    NotBreached,
    /// The password was found, with the given breach count.
    Breached {
        /// Number of times the password appeared in data breaches.
        count: u64,
    },
}

impl BreachResult {
    /// Returns `true` if the password was found in the breach database.
    #[must_use]
    #[inline]
    pub fn is_breached(&self) -> bool {
        matches!(self, Self::Breached { .. })
    }

    /// Returns the breach count, or `0` if the password was not breached.
    #[must_use]
    #[inline]
    pub fn count(&self) -> u64 {
        match self {
            Self::NotBreached => 0,
            Self::Breached { count } => *count,
        }
    }
}

// ---------------------------------------------------------------------------
// HibpResponse
// ---------------------------------------------------------------------------

/// A parsed HIBP range API response.
///
/// The HIBP API returns lines of the form `SUFFIX:COUNT`, where `SUFFIX`
/// is a 35-character uppercase hex string and `COUNT` is a positive
/// integer. This struct holds the parsed entries and supports checking
/// whether a given password appears in the response.
#[derive(Debug, Clone)]
pub struct HibpResponse {
    entries: Vec<(String, u64)>,
}

impl HibpResponse {
    /// Parse the body of a HIBP range API response.
    ///
    /// Each non-empty line must be in the format `SUFFIX:COUNT` where
    /// `SUFFIX` is a 35-character uppercase hex string and `COUNT` is
    /// a positive integer.
    ///
    /// # Errors
    ///
    /// Returns [`HibpError`] if the body is empty, contains malformed
    /// lines, invalid suffixes, or unparseable counts.
    pub fn parse(body: &str) -> Result<Self, HibpError> {
        let mut entries = Vec::new();

        for line in body.split('\n') {
            let line = line.trim();
            if line.is_empty() {
                continue;
            }

            let Some((suffix, count_str)) = line.split_once(':') else {
                return Err(HibpError::new(HibpErrorKind::MalformedLine));
            };

            // Validate suffix: must be exactly 35 uppercase hex characters.
            if suffix.len() != 35 {
                return Err(HibpError::new(HibpErrorKind::InvalidSuffix));
            }
            if !suffix
                .bytes()
                .all(|b| b.is_ascii_hexdigit() && !b.is_ascii_lowercase())
            {
                return Err(HibpError::new(HibpErrorKind::InvalidSuffix));
            }

            let count: u64 = count_str
                .parse()
                .map_err(|_| HibpError::new(HibpErrorKind::InvalidCount))?;

            entries.push((suffix.to_owned(), count));
        }

        if entries.is_empty() {
            return Err(HibpError::new(HibpErrorKind::EmptyResponse));
        }

        Ok(Self { entries })
    }

    /// Check whether the given password appears in this response.
    ///
    /// Computes the SHA-1 hash of the password, extracts the suffix,
    /// and searches the response entries.
    #[must_use]
    pub fn check_password(&self, password: &str) -> BreachResult {
        let prefix = HibpPrefix::from_password(password);
        self.check_prefix(&prefix)
    }

    /// Check whether the password corresponding to a pre-computed
    /// [`HibpPrefix`] appears in this response.
    ///
    /// # Security
    ///
    /// The scan is constant-time per the crate's secret-comparison
    /// contract: each entry is compared with [`constant_time_eq`] and the
    /// loop never short-circuits, so neither *whether* a match occurred nor
    /// its *position* in the list is revealed through timing. Both operands
    /// are already uppercase hex — the response parser rejects lowercase
    /// suffixes and [`HibpPrefix`] is built with an uppercase encoder — so
    /// no case folding is needed.
    #[must_use]
    pub fn check_prefix(&self, prefix: &HibpPrefix) -> BreachResult {
        let suffix = prefix.suffix().as_bytes();
        let mut count = 0u64;
        let mut found = false;
        for (entry_suffix, entry_count) in &self.entries {
            if constant_time_eq(entry_suffix.as_bytes(), suffix) {
                count = *entry_count;
                found = true;
            }
        }
        if found {
            BreachResult::Breached { count }
        } else {
            BreachResult::NotBreached
        }
    }

    /// Returns the number of entries in this response.
    #[must_use]
    #[inline]
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Returns `true` if this response contains no entries.
    #[must_use]
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

// ---------------------------------------------------------------------------
// HibpError
// ---------------------------------------------------------------------------

/// The kind of HIBP parsing error that occurred.
///
/// Private — callers inspect errors through [`HibpError`]'s `Display`
/// and `std::error::Error` implementations.
#[derive(Debug, Clone, PartialEq, Eq)]
enum HibpErrorKind {
    /// A response line did not contain the expected `SUFFIX:COUNT` format.
    MalformedLine,
    /// A suffix was not a valid 35-character uppercase hex string.
    InvalidSuffix,
    /// A count value could not be parsed as a `u64`.
    InvalidCount,
    /// The response body contained no valid entries.
    EmptyResponse,
}

/// Error returned when parsing a HIBP range API response fails.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HibpError {
    kind: HibpErrorKind,
}

impl HibpError {
    const fn new(kind: HibpErrorKind) -> Self {
        Self { kind }
    }
}

impl fmt::Display for HibpError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.kind {
            HibpErrorKind::MalformedLine => f.write_str("hibp: malformed response line"),
            HibpErrorKind::InvalidSuffix => f.write_str("hibp: invalid hash suffix"),
            HibpErrorKind::InvalidCount => f.write_str("hibp: invalid breach count"),
            HibpErrorKind::EmptyResponse => f.write_str("hibp: empty response body"),
        }
    }
}

impl std::error::Error for HibpError {}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    // --- hibp_sha1_hex ---

    #[test]
    fn sha1_hex_of_password() {
        assert_eq!(
            hibp_sha1_hex("password"),
            "5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8",
        );
    }

    // --- HibpPrefix ---

    #[test]
    fn prefix_from_password() {
        let prefix = HibpPrefix::from_password("password");
        assert_eq!(prefix.as_str(), "5BAA6");
    }

    #[test]
    fn prefix_suffix_from_password() {
        let prefix = HibpPrefix::from_password("password");
        assert_eq!(prefix.suffix(), "1E4C9B93F3F0682250B6CF8331B7EE68FD8");
    }

    #[test]
    fn prefix_full_hash_from_password() {
        let prefix = HibpPrefix::from_password("password");
        assert_eq!(
            prefix.full_hash(),
            "5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8",
        );
    }

    // --- HibpResponse::parse ---

    #[test]
    fn parse_valid_response_lf() {
        let body = "1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493\n\
                     0018A45C4D1DEF81644B54AB7F969B88D65:1\n";
        let resp = HibpResponse::parse(body).unwrap();
        assert_eq!(resp.len(), 2);
        assert!(!resp.is_empty());
    }

    #[test]
    fn parse_valid_response_crlf() {
        let body = "1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493\r\n\
                     0018A45C4D1DEF81644B54AB7F969B88D65:1\r\n";
        let resp = HibpResponse::parse(body).unwrap();
        assert_eq!(resp.len(), 2);
    }

    #[test]
    fn check_breached_password() {
        let body = "1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493\n\
                     0018A45C4D1DEF81644B54AB7F969B88D65:1\n";
        let resp = HibpResponse::parse(body).unwrap();
        let result = resp.check_password("password");
        assert!(result.is_breached());
        assert_eq!(result.count(), 3_861_493);
    }

    #[test]
    fn check_non_breached_password() {
        // Response does not contain the suffix for "password".
        let body = "0018A45C4D1DEF81644B54AB7F969B88D65:1\n\
                     AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA1:5\n";
        let resp = HibpResponse::parse(body).unwrap();
        let result = resp.check_password("password");
        assert!(!result.is_breached());
        assert_eq!(result.count(), 0);
    }

    #[test]
    fn check_prefix_breached() {
        let body = "1E4C9B93F3F0682250B6CF8331B7EE68FD8:3861493\n";
        let resp = HibpResponse::parse(body).unwrap();
        let prefix = HibpPrefix::from_password("password");
        let result = resp.check_prefix(&prefix);
        assert!(result.is_breached());
        assert_eq!(result.count(), 3_861_493);
    }

    // --- Parse error cases ---

    #[test]
    fn parse_rejects_empty_body() {
        let err = HibpResponse::parse("").unwrap_err();
        assert_eq!(err, HibpError::new(HibpErrorKind::EmptyResponse));
    }

    #[test]
    fn parse_rejects_whitespace_only() {
        let err = HibpResponse::parse("  \n  \n").unwrap_err();
        assert_eq!(err, HibpError::new(HibpErrorKind::EmptyResponse));
    }

    #[test]
    fn parse_rejects_malformed_line_no_colon() {
        let err = HibpResponse::parse("1E4C9B93F3F0682250B6CF8331B7EE68FD8\n").unwrap_err();
        assert_eq!(err, HibpError::new(HibpErrorKind::MalformedLine));
    }

    #[test]
    fn parse_rejects_wrong_suffix_length() {
        // Suffix is too short (34 chars instead of 35).
        let err = HibpResponse::parse("1E4C9B93F3F0682250B6CF8331B7EE68FD:1\n").unwrap_err();
        assert_eq!(err, HibpError::new(HibpErrorKind::InvalidSuffix));
    }

    #[test]
    fn parse_rejects_lowercase_suffix() {
        let err = HibpResponse::parse("1e4c9b93f3f0682250b6cf8331b7ee68fd8:1\n").unwrap_err();
        assert_eq!(err, HibpError::new(HibpErrorKind::InvalidSuffix));
    }

    #[test]
    fn parse_rejects_invalid_count() {
        let err = HibpResponse::parse("1E4C9B93F3F0682250B6CF8331B7EE68FD8:abc\n").unwrap_err();
        assert_eq!(err, HibpError::new(HibpErrorKind::InvalidCount));
    }

    // --- Error Display ---

    #[test]
    fn error_display_messages_start_with_hibp() {
        let cases = [
            (
                HibpErrorKind::MalformedLine,
                "hibp: malformed response line",
            ),
            (HibpErrorKind::InvalidSuffix, "hibp: invalid hash suffix"),
            (HibpErrorKind::InvalidCount, "hibp: invalid breach count"),
            (HibpErrorKind::EmptyResponse, "hibp: empty response body"),
        ];
        for (kind, expected) in &cases {
            let err = HibpError::new(kind.clone());
            let msg = err.to_string();
            assert!(
                msg.starts_with("hibp:"),
                "expected Display to start with 'hibp:', got: {msg}",
            );
            assert_eq!(&msg, expected);
        }
    }

    #[test]
    fn error_implements_std_error() {
        let err: Box<dyn std::error::Error> =
            Box::new(HibpError::new(HibpErrorKind::MalformedLine));
        assert!(err.source().is_none());
        let _ = err.to_string();
    }

    // --- BreachResult ---

    #[test]
    fn breach_result_not_breached() {
        let r = BreachResult::NotBreached;
        assert!(!r.is_breached());
        assert_eq!(r.count(), 0);
    }

    #[test]
    fn breach_result_breached() {
        let r = BreachResult::Breached { count: 42 };
        assert!(r.is_breached());
        assert_eq!(r.count(), 42);
    }
}