hibp_rs

Overview

hibp_rs is a modern, async Rust client for the HaveIBeenPwned API. It provides a robust, well-documented interface for querying breach data, checking compromised passwords, and managing API rate limits automatically.

Table of Contents

• Features
• Installation
• Usage
  • Basic Usage
  • Rate Limiting Options
  • Enhanced Privacy with Padding
• Development
  • Prerequisites
  • Building
  • Running Tests
• Contributing
• License
• Authors
• Repository

Features

• Full async/await support for efficient non-blocking requests
• Automatic rate limiting based on your HIBP subscription
• Comprehensive breach querying:
  • Search for breaches by account
  • Get all breaches in the system
  • Get specific breach details by name
  • List your subscribed domains
• Password security features:
  • Check passwords against the Pwned Passwords database
  • K-Anonymity support for secure password checking
  • Optional padding for enhanced privacy
• Paste search functionality
• Stealer logs support (for applicable subscriptions)
• Complete error handling and type safety
• Detailed documentation and examples

Installation

Add hibp_rs to your Cargo.toml:

[dependencies]
hibp_rs = "0.1"
tokio = { version = "1.0", features = ["full"] } # Required for async support

Note: You'll need a HIBP API key to use this library. Get one at haveibeenpwned.com/API/Key.

Usage

Basic Usage

use hibp_rs::HaveIBeenPwned;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with automatic rate limiting based on your subscription
    // Works directly with string literals - no .to_string() needed
    let client = HaveIBeenPwned::new_with_auto_rate_limit("your-api-key").await?;

    // Check for breaches
    let breaches = client.get_breaches_for_account("[email protected]").await?;
    for breach in breaches {
        println!("Breach found: {} ({})", breach.title, breach.breach_date);
    }

    // Check if a password has been compromised
    let compromised_count = client.check_password("password123").await?;
    if compromised_count > 0 {
        println!("Password found in {} breaches!", compromised_count);
    }

    Ok(())
}

Rate Limiting Options

The client provides three ways to handle rate limiting:

• Automatic (recommended):

let client = HaveIBeenPwned::new_with_auto_rate_limit("your-api-key").await?;

• Manual:

let client = HaveIBeenPwned::new_with_rate_limit("your-api-key", 100); // 100 requests per minute

• None (not recommended):

let client = HaveIBeenPwned::new("your-api-key");

Enhanced Privacy with Padding

When checking passwords, you can use the padded variants for enhanced privacy:

// Regular password check
let count = client.check_password("my_password").await?;

// Password check with padding
let count = client.check_password_padded("my_password").await?;

Concurrent Operations

The client implements Clone for safe concurrent operations:

use hibp_rs::HaveIBeenPwned;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HaveIBeenPwned::new_with_rate_limit("your-api-key", 100);
    
    // Clone for concurrent use
    let client1 = client.clone();
    let client2 = client.clone();
    
    // Run concurrent operations
    let task1 = tokio::spawn(async move {
        client1.get_breaches_for_account("[email protected]").await
    });
    
    let task2 = tokio::spawn(async move {
        client2.get_breaches_for_account("[email protected]").await
    });
    
    let (result1, result2) = tokio::join!(task1, task2);
    // Rate limiting is automatically shared across clones
    
    Ok(())
}

See the API documentation for complete usage details.

Development

Prerequisites

• Rust 1.88 or later
• Cargo
• A HIBP API key (get one at haveibeenpwned.com)

Building

git clone https://github.com/W4ff1e/hibp_rs.git
cd hibp_rs
cargo build

Running Tests

Create a .env file in the project root with your API key:

HIBP_API_KEY=your-api-key-here

Then run the tests:

cargo test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate and follow the existing code style.

License

This project is licensed under the MIT License.

Authors

• @W4ff1e - Initial work and maintenance
• GitHub Copilot - Pair programming and code assistance

Repository

For more information, visit the GitHub repository.

Stats

---

Made with 💛 by Waffle in collaboration with GitHub Copilot