IdentityLeakPage.hpp

1. Overview

The IdentityLeakPage.hpp header defines the IdentityLeakPage class, a GTKmm (GTK4) UI component that implements BastionGuard’s identity leak detection workflow. The page allows users to:

  • Check an email address against breach intelligence providers (HIBP and LeakCheck)
  • Validate whether a password appears in known breach datasets (HIBP k-anonymity range API)
  • Configure and securely store provider API keys
  • Enable continuous monitoring with background notifications
  • Review results and operational messages in a scrollable log view

Internally, the page coordinates asynchronous operations (thread workers and a dedicated monitor object) and ensures safe UI updates through a centralized logging function.

2. Dependencies and Includes

#include <gtkmm.h>
#include <thread>
#include <atomic>
#include <memory>
#include <string>
  • gtkmm.h – GTK4 widgets (entries, buttons, scrollers, text views) and UI primitives
  • <thread> – background worker and monitoring thread support
  • <atomic> – thread-safe state flags
  • <memory> – ownership of the monitoring instance via std::unique_ptr
  • <string> – email identity, API keys, and log message content

The header forward-declares LeakMonitor to keep compilation dependencies minimal:

class LeakMonitor;

3. Class Declaration and Scope

class IdentityLeakPage : public Gtk::Box

The class derives from Gtk::Box, making it suitable as a page inside a notebook/stack layout or any container-based application shell. It requires a reference to the parent window for dialog prompts and privacy notices.

4. Public Interface

4.1 Constructor and Destructor

explicit IdentityLeakPage(Gtk::Window& parent);
~IdentityLeakPage() override;

The constructor builds the UI, initializes state, loads persisted API key configuration (implementation-defined), and prepares monitoring controls. The destructor ensures worker threads and monitoring activities are terminated safely before the page is destroyed.

5. UI Components

IdentityLeakPage provides a structured form for user inputs (email, API keys, password), execution controls (check buttons), and a log window for results.

5.1 Identity Input

Gtk::Label titleLabel;
Gtk::Entry emailEntry;
  • titleLabel – page title and high-level guidance
  • emailEntry – email address used for breach lookups and monitoring

5.2 HIBP API Controls

Gtk::Entry  apiKeyEntry;
Gtk::Button apiToggleButton;
Gtk::Button saveHibpButton;
  • apiKeyEntry – stores the HIBP API key (hidden by default in UI)
  • apiToggleButton – toggles API key visibility
  • saveHibpButton – persists the HIBP API key (storage implementation-defined)

5.3 Password Breach Check (HIBP Range API)

Gtk::Entry  passwordEntry;
Gtk::Button checkPasswordButton;

Password checks are designed to use privacy-preserving mechanisms (k-anonymity) rather than transmitting the full password to external providers.

  • passwordEntry – password input (must be masked in UI)
  • checkPasswordButton – triggers a password compromise query

5.4 LeakCheck API Controls

Gtk::Entry  leakCheckApiEntry;
Gtk::Button leakCheckToggleButton;
Gtk::Button saveLeakCheckButton;
  • leakCheckApiEntry – LeakCheck API key/token input
  • leakCheckToggleButton – toggles LeakCheck key visibility
  • saveLeakCheckButton – persists LeakCheck credentials

5.5 Monitoring and Execution Controls

Gtk::CheckButton monitorToggle;
Gtk::Button checkButton;
  • monitorToggle – enables/disables continuous identity monitoring
  • checkButton – performs a one-shot breach query on demand

5.6 Log Viewer

Gtk::ScrolledWindow logScroller;
Gtk::TextView logView;
Glib::RefPtr<Gtk::TextBuffer> logBuffer;

A scrollable text view is used to report results, warnings, provider errors, and privacy messages.

6. Worker and Monitoring State

std::thread workerThread;
std::atomic<bool> running { false };

std::unique_ptr<LeakMonitor> monitor;
std::atomic<bool> monitorActive { false };
  • workerThread – executes provider queries without blocking the GTK main loop
  • running – indicates whether a background query is in progress
  • monitor – owns the LeakMonitor instance responsible for periodic checks
  • monitorActive – cached flag reflecting monitoring state

7. Helper Functions

7.1 Logging Helper

void appendLog(const Glib::ustring& text);

Appends text to the UI log buffer in a controlled manner, consolidating all operational output in one place.

7.2 Monitor Lifecycle

void startMonitor(const std::string& email);
void stopMonitor();
  • startMonitor() – constructs and starts the monitoring workflow for the provided email
  • stopMonitor() – stops the monitor and releases associated resources

8. User Actions and Callbacks

void onCheckClicked();
void onCheckPasswordClicked();
void showPrivacyPopup();
void showLeakCheckDisclaimer();

void onToggleApiVisibility();
void onToggleLeakCheckApiVisibility();

void onSaveHibpApi();
void onSaveLeakCheckApi();

void onMonitorToggled();
  • onCheckClicked() – performs a one-shot breach lookup for the entered email
  • onCheckPasswordClicked() – checks whether the entered password is compromised
  • showPrivacyPopup() – displays a privacy notice before querying external services
  • showLeakCheckDisclaimer() – presents provider-specific disclosure for LeakCheck usage
  • onToggleApiVisibility() – toggles HIBP API key masking
  • onToggleLeakCheckApiVisibility() – toggles LeakCheck API key masking
  • onSaveHibpApi() – persists the HIBP API key
  • onSaveLeakCheckApi() – persists the LeakCheck API key
  • onMonitorToggled() – enables/disables continuous monitoring and updates UI state

9. Auto-Update (Scheduled Monitoring)

Continuous monitoring is performed by LeakMonitor (implementation-defined interval), which periodically queries configured providers and uses a callback mechanism to report new findings. The page controls this behavior via monitorToggle and the startMonitor()/stopMonitor() helpers.

10. Settings Storage

Provider credentials and monitoring preferences are expected to be persisted by a dedicated settings store or system keyring integration (implementation-defined). The page exposes explicit save actions for credentials via saveHibpButton and saveLeakCheckButton.

11. Runtime and Security Considerations

  • Threading: all network operations must execute off the GTK main loop; UI updates should be marshaled safely to the main thread when invoked from worker contexts.
  • Credential handling: API keys should be masked in the UI, never logged, and stored only via secure mechanisms (keyring, encrypted store).
  • Password safety: passwords must not be persisted or logged; memory should be cleared where feasible. HIBP password checks should use the k-anonymity range model.
  • Privacy transparency: the page includes explicit disclosure dialogs to inform users when third-party services are queried.
  • Rate limiting: provider quotas must be respected; monitoring intervals should be conservative, and backoff strategies should be applied upon errors.
  • Fail-safe behavior: provider failures should produce actionable log messages without blocking other checks or leaving the UI in an inconsistent state.
Published on:
Last updated on: