LeakCheckWorker (Identity Leak)

1. Overview

The LeakCheckWorker module implements the execution unit used to perform an on-demand Identity Leak check for a given email address. It orchestrates identity normalization, provider selection (HIBP optional, LeakCheck always), leak aggregation, and persistence initialization, while emitting structured progress and diagnostic messages through a caller-provided logging callback.

This worker is intended for interactive checks triggered by the UI (e.g., “Check now”), where the user expects immediate feedback, meaningful status messages, and graceful degradation when premium providers are unavailable.

2. Components and Dependencies

The worker integrates multiple Identity Leak subsystem components:

  • LeakAggregator – orchestrates providers and normalizes returned results
  • HibpProvider – optional provider for full breach coverage (requires API key)
  • LeakCheckProvider – always-enabled fallback provider (limited coverage)
  • LeakDatabase – initializes and ensures identity persistence
  • HashUtil – SHA256 hashing used to derive a stable identity identifier
  • IdentityLeakConfig – loads configured API keys and feature flags

Additional dependencies:

  • glib/gi18n – localized UI/log output via _()
  • C++ standard library – smart pointers, exceptions, containers

3. Public API

3.1 Construction

LeakCheckWorker::LeakCheckWorker(
  const std::string& e,
  LogFn logger
)

The worker is constructed with:

  • email – the identity to be checked
  • log – a logging callback (LogFn) used to emit progress messages

The logger is stored using move semantics to support flexible integration (UI text area, log file, notification system, etc.).

3.2 run()

void LeakCheckWorker::run()

Executes the full leak check workflow synchronously, emitting localized progress output via log().

4. Execution Flow

4.1 Identity Normalization (Hashing)

The worker begins by normalizing the identity and generating a stable identifier:

  • Logs “Normalizing identity…”
  • Computes emailHash as SHA256(email) via HashUtil::sha256()

This hash is used for local persistence without storing the raw email address.

4.2 Local Persistence Initialization

The worker initializes the local database and ensures the identity is registered:

  • Instantiates LeakDatabase db; (which opens DB and ensures schema)
  • Calls db.ensureIdentity(emailHash)

This step guarantees that subsequent leak records can be associated with an existing identity key.

4.3 Aggregator Initialization

A new LeakAggregator is constructed to coordinate provider queries and normalization logic.

4.4 Provider Selection and Capability Mode

The worker selects providers based on configuration:

  • Reads the HIBP API key from IdentityLeakConfig::hibpApiKey()
  • Sets hibpEnabled if the key is non-empty

Behavior:

  • If HIBP is enabled:
    • Adds HibpProvider to the aggregator
    • Logs that HIBP is active and provides full coverage
  • If HIBP is not enabled:
    • Logs that HIBP is not configured
    • Logs that the system will fall back to LeakCheck with limited coverage

Regardless of HIBP availability, the worker always adds:

  • LeakCheckProvider (fallback baseline coverage)

4.5 Query Execution

The worker executes the provider query pipeline through the aggregator:

results = aggregator.queryAll(email);

Error handling:

  • Any exception thrown by providers or aggregation logic is caught
  • An error message is logged via log()
  • The worker exits early

This makes the worker safe for UI usage: failures result in user-visible diagnostics rather than a crash.

4.6 “No Breach” Outcome

If no results are returned:

  • The worker logs a positive outcome (no leak detected)
  • The worker returns immediately

5. Expected Downstream Behavior (Partial Snippet Context)

The provided code ends after the “no breach” case. Based on the database and new-leak detection modules in the subsystem, the typical next steps (not shown in the snippet) are:

  • Iterate over results
  • Determine which breaches are new via LeakDatabase::isNewLeak()
  • Persist new breaches via LeakDatabase::storeLeak()
  • Log a summary suitable for UI (new breaches vs already-known breaches)

If your implementation follows this pattern, it is recommended to log clearly whether an alert is due to a truly new event or simply an already-known breach resurfacing in provider output.

6. Runtime and Security Considerations

  • PII minimization: the worker hashes the email before persistence, reducing local exposure risk
  • Provider privacy: the raw email is sent to external providers during lookup; the UI should ensure user consent and privacy policy alignment
  • Graceful degradation: HIBP is optional; LeakCheck provides a baseline capability when HIBP is not configured
  • Operational transparency: the worker logs capability mode (“full coverage” vs “limited coverage”) to avoid misleading results
  • Exception containment: provider and parsing failures are caught, preventing UI thread failures
  • Blocking behavior: run() is synchronous; it should execute on a worker thread if called from a GUI event handler
Published on:
Last updated on: