DarkStrata Credential Check SDK for Rust

A Rust SDK for checking if credentials have been exposed in data breaches using the DarkStrata API with k-anonymity privacy protection.

Features

Privacy-First: Uses k-anonymity to ensure your credentials are never exposed
Async/Await: Built on tokio for efficient async operations
Batch Processing: Check multiple credentials efficiently with optimized API calls
Automatic Retries: Exponential backoff for transient failures
Response Caching: Reduces API calls with intelligent caching
Type-Safe: Comprehensive Rust types with full error handling
Zero Unsafe Code: 100% safe Rust implementation

Prerequisites

Get an API key from https://darkstrata.io
Rust 1.70 or higher

Installation

Add this to your Cargo.toml:

[dependencies]
darkstrata-credential-check = "0.1"
tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }

Quick Start

use darkstrata_credential_check::{DarkStrataCredentialCheck, ClientOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client with your API key
    let client = DarkStrataCredentialCheck::new(
        ClientOptions::new("your-api-key")
    )?;

    // Check a single credential
    let result = client.check("user@example.com", "password123", None).await?;

    if result.found {
        println!("This credential has been compromised!");
    } else {
        println!("Credential not found in any known breaches.");
    }

    Ok(())
}

Usage

Check a Single Credential

let result = client.check("user@example.com", "password123", None).await?;

println!("Found: {}", result.found);
println!("Prefix: {}", result.metadata.prefix);
println!("Total matches: {}", result.metadata.total_results);

Check a Pre-computed Hash

If you've already computed the SHA-256 hash of the credential (email:password):

use darkstrata_credential_check::crypto_utils;

// Compute hash yourself
let hash = crypto_utils::hash_credential("user@example.com", "password123");

// Or use a pre-computed hash
let result = client.check_hash(&hash, None).await?;

Batch Check

Check multiple credentials efficiently:

use darkstrata_credential_check::Credential;

let credentials = vec![
    Credential::new("alice@example.com", "password1"),
    Credential::new("bob@example.com", "password2"),
    Credential::new("carol@example.com", "password3"),
];

let results = client.check_batch(&credentials, None).await?;

for (cred, result) in credentials.iter().zip(results.iter()) {
    println!("{}: {}", cred.email, if result.found { "compromised" } else { "safe" });
}

Check Options

Filter by date or use a custom HMAC key:

use darkstrata_credential_check::CheckOptions;

// Filter to breaches since a specific date
let options = CheckOptions::new()
    .since_epoch_day(19724);  // 2024-01-01

let result = client.check("user@example.com", "password", Some(options)).await?;

// Use a custom HMAC key for deterministic results
let options = CheckOptions::new()
    .client_hmac("0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef");

let result = client.check("user@example.com", "password", Some(options)).await?;

Client Configuration

use std::time::Duration;

let client = DarkStrataCredentialCheck::new(
    ClientOptions::new("your-api-key")
        .base_url("https://custom.api.com/v1/")
        .timeout(Duration::from_secs(60))
        .retries(5)
        .enable_caching(true)
        .cache_ttl(Duration::from_secs(1800))
)?;

Error Handling

The SDK provides detailed error types for comprehensive error handling:

use darkstrata_credential_check::DarkStrataError;

match client.check("user@example.com", "password", None).await {
    Ok(result) => {
        println!("Found: {}", result.found);
    }
    Err(DarkStrataError::Authentication { .. }) => {
        println!("Invalid API key");
    }
    Err(DarkStrataError::RateLimit { retry_after }) => {
        if let Some(duration) = retry_after {
            println!("Rate limited. Retry after {:?}", duration);
        }
    }
    Err(DarkStrataError::Validation { message, field }) => {
        println!("Validation error: {} (field: {:?})", message, field);
    }
    Err(e) if e.is_retryable() => {
        println!("Transient error, can retry: {}", e);
    }
    Err(e) => {
        println!("Error: {}", e);
    }
}

How It Works

The SDK uses k-anonymity to protect your credentials:

Your credential is hashed using SHA-256: SHA256(email:password)
Only the first 5 characters (prefix) are sent to the API
The API returns all hashes matching that prefix (1-in-1,000,000 anonymity)
The SDK checks locally if your full hash exists in the returned set
Timing-safe comparison prevents timing attacks

Your actual credentials or full hashes are never sent to the server.

API Reference