ILeakProvider.hpp

1. Overview

The ILeakProvider.hpp header defines the ILeakProvider abstract interface, which standardizes access to external data breach and identity leak intelligence services within BastionGuard.

This interface enables a pluggable provider architecture, allowing multiple breach intelligence sources to be integrated through a unified contract.

Functionally, ILeakProvider provides:

  • A common abstraction for email breach lookup services
  • Support for multiple heterogeneous providers
  • Interoperability with aggregation and monitoring systems
  • Loose coupling between backend logic and data sources
  • Extensibility for future provider integrations

2. Dependencies and Includes

#include <string>
#include <vector>
#include "../model/LeakRecord.hpp"
  • <string> – identity parameters and provider names
  • <vector> – container for breach records
  • LeakRecord.hpp – standardized leak data model

3. Interface Declaration and Scope

class ILeakProvider

ILeakProvider is a pure abstract base class defining the minimum functionality required for any identity leak intelligence provider.

It follows the interface segregation principle and supports runtime polymorphism.

4. Public Interface

4.1 Virtual Destructor

virtual ~ILeakProvider() = default;

Ensures proper destruction of derived provider objects through base-class pointers.

4.2 Email Breach Lookup

virtual std::vector<LeakRecord>
checkEmail(const std::string& email) = 0;

Performs a breach lookup for the specified email address.

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

Implementations are responsible for handling:

  • Authentication
  • Rate limiting
  • Error handling
  • Response parsing

4.3 Provider Identification

virtual std::string name() const = 0;

Returns a unique, human-readable name identifying the provider.

This value is used for logging, UI presentation, and diagnostics.

5. Polymorphic Usage Model

ILeakProvider is typically used through base-class pointers or smart pointers:

std::unique_ptr<ILeakProvider> provider;
provider->checkEmail(userEmail);

This enables runtime selection and composition of different provider implementations.

6. Integration with Aggregation Framework

Implementations of ILeakProvider are consumed by higher-level components such as:

  • LeakAggregator
  • LeakMonitor
  • Identity leak dashboards
  • Alerting subsystems

7. Provider Lifecycle Management

Providers are typically:

  • Constructed during application initialization
  • Configured with API keys and endpoints
  • Registered with aggregation services
  • Destroyed during application shutdown

Resource ownership is usually managed via std::unique_ptr.

8. Error Handling Contract

Implementations should follow consistent error semantics:

  • Return empty vectors on transient failures
  • Log detailed diagnostics internally
  • Avoid throwing uncaught exceptions
  • Respect provider-specific retry policies

9. Extensibility Guidelines

New providers should:

  • Derive publicly from ILeakProvider
  • Implement all pure virtual methods
  • Return normalized LeakRecord instances
  • Use HttpClient for network access
  • Support configuration through centralized settings

10. Settings and Configuration

Provider-specific settings (API keys, quotas, endpoints) are typically stored in:

  • Encrypted configuration files
  • System keyrings
  • Secure environment variables (development only)

11. Security and Privacy Considerations

  • PII handling: email addresses constitute personal data and must be protected accordingly.
  • Transport security: all provider communications must use TLS encryption.
  • Data minimization: only required fields should be retained.
  • Auditability: provider activity should be traceable for security reviews.

12. Runtime and Maintainability Considerations

  • Backward compatibility: interface changes affect all implementations and must be managed carefully.
  • Testing: mock implementations should be used for unit and integration tests.
  • Resilience: failures in one provider should not compromise the entire aggregation pipeline.
  • Documentation: each implementation must document provider-specific behavior.
Published on:
Last updated on: