use std::fmt;
use serde::Deserialize;
use sha1::{Digest as _, Sha1};
use crate::Address;
const API_BASE: &str = "https://haveibeenpwned.com/api/v3/";
const BODY_LIMIT: usize = 2 * 1024 * 1024;
#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct Breach {
name: String,
title: String,
domain: String,
breach_date: String,
added_date: String,
pwn_count: u64,
data_classes: Vec<String>,
is_verified: bool,
is_sensitive: bool,
}
impl Breach {
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub fn title(&self) -> &str {
&self.title
}
#[must_use]
pub fn domain(&self) -> &str {
&self.domain
}
#[must_use]
pub fn breach_date(&self) -> &str {
&self.breach_date
}
#[must_use]
pub fn added_date(&self) -> &str {
&self.added_date
}
#[must_use]
pub const fn affected_accounts(&self) -> u64 {
self.pwn_count
}
#[must_use]
pub fn data_classes(&self) -> &[String] {
&self.data_classes
}
#[must_use]
pub const fn is_verified(&self) -> bool {
self.is_verified
}
#[must_use]
pub const fn is_sensitive(&self) -> bool {
self.is_sensitive
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ExposureUnavailable {
Transport,
Authentication,
AccessDenied,
RateLimited {
retry_after: Option<std::time::Duration>,
},
Provider,
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ExposureStatus {
Exposed(Vec<Breach>),
NotFound,
Unavailable(ExposureUnavailable),
}
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum HashRangeStatus {
Exposed(Vec<String>),
NotFound,
Unavailable(ExposureUnavailable),
}
#[derive(Clone)]
pub struct BreachClient {
http: tez::Client,
}
impl BreachClient {
pub fn new(
api_key: impl AsRef<str>,
user_agent: impl AsRef<str>,
) -> Result<Self, BreachClientError> {
if api_key.as_ref().len() != 32
|| !api_key
.as_ref()
.bytes()
.all(|byte| byte.is_ascii_hexdigit())
{
return Err(BreachClientError::Configuration(
"API key must be 32 hexadecimal characters",
));
}
if user_agent.as_ref().trim().is_empty() {
return Err(BreachClientError::Configuration(
"user agent must not be empty",
));
}
let authentication = tez::auth::ApiKeyAuth::new(
"hibp-api-key",
secrecy::SecretString::from(api_key.as_ref().to_owned()),
)
.map_err(|_| BreachClientError::Configuration("API key is invalid"))?;
let http = tez::Client::builder()
.base_url(API_BASE)
.user_agent(user_agent)
.timeout(std::time::Duration::from_secs(15))
.auth(authentication)
.build()
.map_err(|_| BreachClientError::Initialization)?;
Ok(Self { http })
}
pub async fn lookup(&self, address: &Address) -> ExposureStatus {
let mut target = match url::Url::parse(API_BASE) {
Ok(target) => target,
Err(_) => return ExposureStatus::Unavailable(ExposureUnavailable::Provider),
};
match target.path_segments_mut() {
Ok(mut path) => {
path.push("breachedaccount");
path.push(&address.to_string());
}
Err(()) => return ExposureStatus::Unavailable(ExposureUnavailable::Provider),
}
target
.query_pairs_mut()
.append_pair("truncateResponse", "false");
let response = self.http.get(target.as_str()).send().await;
let response = match response {
Ok(response) => response,
Err(_) => return ExposureStatus::Unavailable(ExposureUnavailable::Transport),
};
match response.status().as_u16() {
200 => {
match crate::provider_response::json::<Vec<Breach>>(response, BODY_LIMIT).await {
Ok(breaches) if !breaches.is_empty() => ExposureStatus::Exposed(breaches),
Ok(_) | Err(_) => ExposureStatus::Unavailable(ExposureUnavailable::Provider),
}
}
status => account_status(status, crate::provider_response::retry_after(&response)),
}
}
pub async fn lookup_by_hash_range(&self, address: &Address) -> HashRangeStatus {
let (prefix, suffix) = hash_range(address);
let response = self
.http
.get(format!("{API_BASE}breachedaccount/range/{prefix}"))
.send()
.await;
let response = match response {
Ok(response) => response,
Err(_) => return HashRangeStatus::Unavailable(ExposureUnavailable::Transport),
};
match response.status().as_u16() {
200 => {
match crate::provider_response::json::<Vec<HashRange>>(response, BODY_LIMIT).await {
Ok(entries) => match_hash_range(entries, &suffix),
Err(_) => HashRangeStatus::Unavailable(ExposureUnavailable::Provider),
}
}
status => range_status(status, crate::provider_response::retry_after(&response)),
}
}
}
fn account_status(status: u16, retry_after: Option<std::time::Duration>) -> ExposureStatus {
match status {
404 => ExposureStatus::NotFound,
401 => ExposureStatus::Unavailable(ExposureUnavailable::Authentication),
403 => ExposureStatus::Unavailable(ExposureUnavailable::AccessDenied),
429 => ExposureStatus::Unavailable(ExposureUnavailable::RateLimited { retry_after }),
_ => ExposureStatus::Unavailable(ExposureUnavailable::Provider),
}
}
fn range_status(status: u16, retry_after: Option<std::time::Duration>) -> HashRangeStatus {
match status {
404 => HashRangeStatus::NotFound,
401 => HashRangeStatus::Unavailable(ExposureUnavailable::Authentication),
403 => HashRangeStatus::Unavailable(ExposureUnavailable::AccessDenied),
429 => HashRangeStatus::Unavailable(ExposureUnavailable::RateLimited { retry_after }),
_ => HashRangeStatus::Unavailable(ExposureUnavailable::Provider),
}
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct HashRange {
hash_suffix: String,
websites: Vec<String>,
}
fn hash_range(address: &Address) -> (String, String) {
let normalized = address.to_string().to_lowercase();
let digest = Sha1::digest(normalized.as_bytes());
let hash = hex(&digest);
(hash[..6].to_owned(), hash[6..].to_owned())
}
fn match_hash_range(entries: Vec<HashRange>, suffix: &str) -> HashRangeStatus {
let mut matches = entries
.into_iter()
.filter(|entry| entry.hash_suffix.eq_ignore_ascii_case(suffix));
let Some(mut matched) = matches.next() else {
return HashRangeStatus::NotFound;
};
if matches.next().is_some()
|| matched.websites.is_empty()
|| matched.websites.iter().any(|name| name.trim().is_empty())
{
return HashRangeStatus::Unavailable(ExposureUnavailable::Provider);
}
matched.websites.sort_unstable();
matched.websites.dedup();
HashRangeStatus::Exposed(matched.websites)
}
fn hex(bytes: &[u8]) -> String {
const DIGITS: &[u8; 16] = b"0123456789ABCDEF";
let mut output = String::with_capacity(bytes.len() * 2);
for byte in bytes {
output.push(char::from(DIGITS[usize::from(byte >> 4)]));
output.push(char::from(DIGITS[usize::from(byte & 0x0f)]));
}
output
}
impl fmt::Debug for BreachClient {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("BreachClient")
.finish_non_exhaustive()
}
}
#[derive(Clone, Copy, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum BreachClientError {
#[error("breach client configuration is invalid: {0}")]
Configuration(&'static str),
#[error("breach HTTP client could not be initialized")]
Initialization,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn client_debug_redacts_api_key() {
let key = "0123456789abcdef0123456789abcdef";
let client = BreachClient::new(key, "pata-tests/1").unwrap();
assert!(!format!("{client:?}").contains(key));
}
#[test]
fn invalid_configuration_does_not_echo_secrets() {
let error = BreachClient::new("private-key\n", "pata-tests/1").unwrap_err();
assert!(!error.to_string().contains("private-key"));
}
#[test]
fn hash_range_matches_hibp_normalization() {
let address = Address::parse("test@example.com").unwrap();
let (prefix, suffix) = hash_range(&address);
assert_eq!(prefix, "567159");
assert_eq!(suffix, "D622FFBB50B11B0EFD307BE358624A26EE");
}
#[test]
fn hash_range_discards_unrelated_entries_and_normalizes_names() {
let status = match_hash_range(
vec![
HashRange {
hash_suffix: "unrelated".to_owned(),
websites: vec!["Private".to_owned()],
},
HashRange {
hash_suffix: "MATCH".to_owned(),
websites: vec!["Gawker".to_owned(), "Adobe".to_owned(), "Adobe".to_owned()],
},
],
"match",
);
assert_eq!(
status,
HashRangeStatus::Exposed(vec!["Adobe".to_owned(), "Gawker".to_owned()])
);
}
#[test]
fn hash_range_rejects_empty_breach_names() {
let status = match_hash_range(
vec![HashRange {
hash_suffix: "MATCH".to_owned(),
websites: vec![String::new()],
}],
"match",
);
assert_eq!(
status,
HashRangeStatus::Unavailable(ExposureUnavailable::Provider)
);
}
#[test]
fn account_statuses_preserve_provider_meaning() {
let retry_after = Some(std::time::Duration::from_secs(30));
assert_eq!(account_status(404, None), ExposureStatus::NotFound);
assert_eq!(
account_status(401, None),
ExposureStatus::Unavailable(ExposureUnavailable::Authentication)
);
assert_eq!(
account_status(403, None),
ExposureStatus::Unavailable(ExposureUnavailable::AccessDenied)
);
assert_eq!(
account_status(429, retry_after),
ExposureStatus::Unavailable(ExposureUnavailable::RateLimited { retry_after })
);
assert_eq!(
account_status(503, None),
ExposureStatus::Unavailable(ExposureUnavailable::Provider)
);
}
#[test]
fn empty_hash_range_is_an_authoritative_absence() {
assert_eq!(range_status(404, None), HashRangeStatus::NotFound);
}
#[test]
fn hash_range_statuses_preserve_provider_failures() {
let retry_after = Some(std::time::Duration::from_secs(30));
assert_eq!(
range_status(401, None),
HashRangeStatus::Unavailable(ExposureUnavailable::Authentication)
);
assert_eq!(
range_status(403, None),
HashRangeStatus::Unavailable(ExposureUnavailable::AccessDenied)
);
assert_eq!(
range_status(429, retry_after),
HashRangeStatus::Unavailable(ExposureUnavailable::RateLimited { retry_after })
);
assert_eq!(
range_status(503, None),
HashRangeStatus::Unavailable(ExposureUnavailable::Provider)
);
}
#[test]
fn breach_decodes_the_provider_field_names() {
let breach: Breach = serde_json::from_str(
r#"{
"Name": "Example",
"Title": "Example breach",
"Domain": "example.com",
"BreachDate": "2026-01-02",
"AddedDate": "2026-01-03T04:05:06Z",
"PwnCount": 42,
"DataClasses": ["Email addresses"],
"IsVerified": true,
"IsSensitive": false
}"#,
)
.unwrap();
assert_eq!(breach.name(), "Example");
assert_eq!(breach.affected_accounts(), 42);
}
}