Crate darkstrata_credential_check 

DarkStrata Credential Check SDK for Rust

This SDK provides a secure way to check if credentials have been exposed in data breaches using k-anonymity privacy protection.

Overview

The SDK sends only a 5 or 6-character hash prefix to the API (k-anonymity), ensuring that your actual credentials are never exposed. The API returns all hashes matching the prefix, and the client checks for a match locally using timing-safe comparison.

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!");
    }

    Ok(())
}

Batch Checking

use darkstrata_credential_check::{DarkStrataCredentialCheck, ClientOptions, Credential};

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

    let credentials = vec![
        Credential::new("alice@example.com", "pass1"),
        Credential::new("bob@example.com", "pass2"),
    ];

    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" });
    }

    Ok(())
}

Configuration Options

use darkstrata_credential_check::{DarkStrataCredentialCheck, ClientOptions};
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))
)?;

Check Options

use darkstrata_credential_check::{DarkStrataCredentialCheck, ClientOptions, CheckOptions};

let client = DarkStrataCredentialCheck::new(ClientOptions::new("your-api-key"))?;

// Filter by date
let result = client.check(
    "user@example.com",
    "password",
    Some(CheckOptions::new().since_epoch_day(19724))
).await?;

// Use custom HMAC key
let result = client.check(
    "user@example.com",
    "password",
    Some(CheckOptions::new().client_hmac(
        "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ))
).await?;

Error Handling

use darkstrata_credential_check::{DarkStrataCredentialCheck, ClientOptions, DarkStrataError};

let client = DarkStrataCredentialCheck::new(ClientOptions::new("your-api-key"))?;

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

Modules

config

Configuration constants.

crypto_utils

Cryptographic utilities for advanced usage.

Structs

CheckMetadata

Metadata about a check operation.

CheckOptions

Options for individual check operations.

CheckResult

Result of a credential check.

ClientOptions

Configuration options for the DarkStrata client.

Credential

A credential (email and password pair) to check.

CredentialInfo

Information about the checked credential.

DarkStrataCredentialCheck

DarkStrata credential check client.

Enums

DarkStrataError

Main error type for the DarkStrata SDK.

HmacSource

Source of the HMAC key used for hashing.

SinceFilter

Filter for specifying a “since” date for breach results.

Functions

is_retryable_status

Check if an HTTP status code indicates a retryable error.

Type Aliases

Result

Result type alias for DarkStrata operations.