HibpProvider.hpp

1. Overview

The HibpProvider.hpp header defines the HibpProvider class, a concrete implementation of the ILeakProvider interface that integrates the Have I Been Pwned (HIBP) breach database into the BastionGuard identity protection subsystem.

This provider enables BastionGuard to query HIBP for compromised accounts and convert raw API responses into normalized LeakRecord objects.

Functionally, HibpProvider provides:

  • Authenticated access to the HIBP breach API
  • Email-based breach lookup functionality
  • Transformation of API responses into internal data models
  • Provider-specific severity evaluation
  • Compliance with the ILeakProvider contract
  • Standardized provider identification

2. Dependencies and Includes

#include "ILeakProvider.hpp"
#include "../model/LeakRecord.hpp"

#include <string>
#include <vector>
  • ILeakProvider.hpp – abstract provider interface
  • LeakRecord.hpp – normalized breach data model
  • <string> – API key storage and identity parameters
  • <vector> – container for returned breach records

3. Class Declaration and Scope

class HibpProvider final : public ILeakProvider

The class is marked final, preventing further inheritance and ensuring stable behavior within the provider ecosystem.

It follows the strategy pattern through the ILeakProvider interface.

4. Public Interface

4.1 Constructor

explicit HibpProvider(const std::string& apiKey);

Initializes the provider with the supplied HIBP API key.

  • apiKey – authentication token for HIBP services

The key is stored internally and used for all subsequent API requests.

4.2 Email Breach Lookup

std::vector<LeakRecord>
checkEmail(const std::string& email) override;

Queries the HIBP breach database for records associated with the specified email address.

  • email – identity to be checked
  • Return value – list of normalized breach records

This method implements the ILeakProvider interface contract and is invoked by aggregation components.

4.3 Provider Identification

std::string name() const override { return "HIBP"; }

Returns a human-readable identifier for this provider implementation.

5. Internal State

std::string apiKey;

Stores the API authentication key required for accessing HIBP endpoints.

The key should be retrieved from secure storage and never logged in plaintext.

6. Internal Logic

6.1 Severity Computation Helper

LeakRecord::Severity computeSeverity(
    const std::vector<std::string>& dataClasses
) const;

Computes the appropriate severity level based on the categories of data exposed in a given breach.

Typical evaluation criteria include:

  • Presence of credentials (passwords, tokens)
  • Financial or identity documents
  • Government identifiers
  • Biometric or health data

7. API Interaction Workflow

A typical request cycle includes:

  • Constructing authenticated HTTPS requests
  • Injecting API key into request headers
  • Encoding email parameters
  • Handling HTTP status codes and rate limits
  • Parsing JSON responses
  • Mapping API fields to LeakRecord

8. Integration with Aggregation and Monitoring

HibpProvider is typically used by:

  • LeakAggregator for multi-provider queries
  • LeakMonitor for continuous monitoring
  • Identity leak dashboards
  • Alerting and notification systems

9. Auto-Update (Scheduled Refresh)

This provider does not implement internal scheduling. Query frequency is controlled by higher-level components.

10. Settings and Credential Management

API keys are typically managed through:

  • Encrypted configuration stores
  • System keyrings
  • Environment variables (development only)

Rotation and revocation procedures should be supported by administrative tools.

11. Compliance and Provider Policies

  • Rate limits: HIBP enforces strict request quotas; callers must implement throttling and backoff strategies.
  • Attribution: API usage may require proper attribution according to HIBP terms.
  • Data usage: retrieved breach data must be handled in compliance with privacy regulations.

12. Runtime and Security Considerations

  • Secret handling: API keys must be protected in memory and erased when no longer needed.
  • TLS enforcement: all network communications must use secure HTTPS connections.
  • Error isolation: API failures should not block other providers in aggregation workflows.
  • Input sanitization: email parameters must be validated before transmission.
  • Defensive parsing: JSON responses must be validated to prevent malformed data propagation.
Published on:
Last updated on: