LeakMonitor.hpp

1. Overview

The LeakMonitor.hpp header defines the LeakMonitor class, a background monitoring component responsible for periodically checking whether a monitored identity (typically an email address) has been involved in new data breaches.

This module operates asynchronously in a dedicated worker thread and integrates with external breach intelligence services to provide continuous identity protection.

Functionally, LeakMonitor provides:

  • Periodic monitoring of email addresses for data leaks
  • Integration with Have I Been Pwned (HIBP) and LeakCheck services
  • Automatic fallback between providers
  • Thread-safe notification delivery
  • Lifecycle management of background monitoring threads
  • Decoupling between monitoring logic and UI components

2. Dependencies and Includes

#include <string>
#include <thread>
#include <atomic>
#include <functional>
  • <string> – identity representation (email)
  • <thread> – background worker thread management
  • <atomic> – thread-safe state signaling
  • <functional> – callback abstraction

3. Class Declaration and Scope

class LeakMonitor

The class encapsulates its own execution thread and follows RAII principles for safe startup and shutdown.

It is designed to be instantiated per monitored identity.

4. Public Interface

4.1 Notification Callback Type

using NotifyFn = std::function<void(const std::string&)>;

Defines the signature for notification callbacks invoked when new breach events are detected.

  • Parameter – human-readable notification message

4.2 Constructor

explicit LeakMonitor(
    const std::string& email,
    NotifyFn notify
);

Initializes a monitoring instance for the specified email address and registers a notification callback.

  • email – identity to be monitored
  • notify – callback invoked on detected events

4.3 Destructor

~LeakMonitor();

Ensures that monitoring is stopped and that the worker thread is joined before destruction.

4.4 Start Monitoring

void start();

Launches the background monitoring loop in a dedicated worker thread.

4.5 Stop Monitoring

void stop();

Signals the worker thread to terminate and waits for graceful shutdown.

5. Internal State and Data Model

std::string email;
NotifyFn notify;
std::thread worker;
std::atomic<bool> running{false};
  • email – monitored identity (stored in clear form internally)
  • notify – registered notification callback
  • worker – background execution thread
  • running – atomic flag controlling loop execution

6. Internal Logic

6.1 Monitoring Loop

void loop();

Implements the periodic monitoring workflow. The loop runs while running is set to true.

A typical cycle includes:

  • Querying HIBP if API credentials are configured
  • Falling back to LeakCheck when necessary
  • Comparing results with previous state
  • Detecting newly reported breaches
  • Dispatching notifications
  • Sleeping for a configured interval

7. Threading and Concurrency Model

LeakMonitor uses a single background thread per instance.

  • Start/stop operations are thread-safe
  • State transitions are controlled via atomic flags
  • Callback invocation is designed to be safe across threads
  • UI updates must be marshaled to the main thread by callers

8. Integration with Identity Protection System

LeakMonitor is typically integrated with:

  • Identity leak management UI pages
  • Notification subsystems
  • Background privacy services
  • User alerting mechanisms

9. Auto-Update (Scheduled Refresh)

Monitoring intervals are managed internally by the loop() implementation. Higher-level components may configure timing policies.

10. Settings and Configuration

API keys, refresh intervals, and provider preferences are typically managed by external configuration stores and injected into the monitoring workflow.

11. Privacy and Data Protection

  • Data minimization: email addresses should be logged only in hashed or anonymized form.
  • Secure storage: API credentials must be stored in protected keyrings.
  • Transport security: all provider communications must use encrypted channels (TLS).
  • User consent: monitoring should be enabled only after explicit user approval.

12. Runtime and Security Considerations

  • Thread lifecycle: failure to stop the worker thread before destruction may cause undefined behavior.
  • Resource usage: excessive polling intervals may impact system performance or API quotas.
  • Error isolation: network failures should be handled gracefully without terminating the monitor.
  • Resilience: temporary provider outages should trigger retry/backoff strategies.
  • Notification storms: duplicate alerts must be suppressed through state comparison.
Published on:
Last updated on: