BankPage.hpp

1. Overview

The BankPage.hpp header defines the BankPage class, a GTKmm (GTK4) UI component responsible for managing a bank/financial domain list and a user-maintained whitelist. This page supports manual refresh, scheduled auto-updates, and integration with a secure browsing workflow (via a forward-declared SecureBrowser).

Functionally, BankPage provides:

  • Display of the current bank list (from JSON sources)
  • User whitelist management (add / load / save)
  • Manual refresh actions and status reporting
  • Optional auto-update every 6 hours, controlled via a GTK switch and timer connection
  • Path helpers to locate user/system data under BastionGuard directories

2. Dependencies and Includes

#include <gtkmm.h>
#include <vector>
#include <string>
  • gtkmm.h – GTK4 C++ widgets and signal/timer primitives
  • <vector> – container for whitelist entries
  • <string> – paths, URLs, domains, and UI text

3. Class Declaration and Scope

class BankPage : public Gtk::Box

The class derives from Gtk::Box, making it suitable as a page within a notebook or any container-based layout.

The header forward-declares SecureBrowser to avoid including browser headers at compile time and to reduce coupling:

// forward
class SecureBrowser;

4. Public Interface

4.1 Constructor

BankPage();

Initializes the bank list/whitelist UI, loads persisted settings, and prepares auto-update state (switch + timer connection) based on user configuration.

5. UI Components

BankPage exposes a composite layout consisting of input fields, controls, scrollers, text views, and a status label.

5.1 URL Entry and Refresh

Gtk::Entry  entry_url_;
Gtk::Button btn_refresh_;
  • entry_url_ – URL input used as a source for updating the bank list
  • btn_refresh_ – triggers a manual refresh workflow

5.2 Auto-Update Controls

Gtk::Switch auto_update_switch_;
Gtk::Label  auto_update_label_;

Toggle and label controlling and describing periodic updates. When enabled, a timer task triggers bank list refresh at a fixed interval (documented as 6 hours).

5.3 Whitelist Controls

Gtk::Entry  whitelist_entry_;
Gtk::Button btn_add_whitelist_;

Entry and action button used to add a domain to the whitelist.

5.4 Bank List and Whitelist Views

Gtk::ScrolledWindow scroller_banks_;
Gtk::ScrolledWindow scroller_white_;
Gtk::TextView txt_banks_;
Gtk::TextView txt_whitelist_;

Two independent scrollable text views are used to display:

  • txt_banks_ – the current bank list (loaded from JSON)
  • txt_whitelist_ – the user whitelist

5.5 Status Label

Gtk::Label lbl_status_;

Displays operational status messages (success/failure of downloads, save operations, parsing errors, and current auto-update state).

6. Internal State and Data Model

std::vector<std::string> whitelist_;
std::string selected_bank_url_;
bool auto_update_enabled_ = false;
sigc::connection auto_update_conn_;
  • whitelist_ – in-memory list of allowed domains
  • selected_bank_url_ – the currently selected bank URL/domain from the list
  • auto_update_enabled_ – cached flag reflecting current auto-update state
  • auto_update_conn_ – signal/timer connection handle used to stop the auto-update task safely

7. User Actions (Callbacks)

void on_refresh_clicked();
void on_add_whitelist_clicked();
void on_open_browser_clicked();
void on_close_browser_clicked();
  • on_refresh_clicked() – executes manual refresh and updates UI/status
  • on_add_whitelist_clicked() – validates input, updates whitelist, persists changes
  • on_open_browser_clicked() – opens the secure browser workflow (implementation-defined)
  • on_close_browser_clicked() – closes the secure browser instance (implementation-defined)

8. Internal Logic

8.1 Bank List Population

void populate_bank_list();

Reads the bank list JSON and updates the UI. This method is also responsible for maintaining selected_bank_url_ according to the loaded data and/or user selection policy.

8.2 Whitelist Persistence

void load_whitelist();
void save_whitelist();

Loads and saves the whitelist to a dedicated user data file. Persistence is intended to be durable across sessions and to keep the UI synchronized with stored configuration.

9. Auto-Update (Scheduled Refresh)

bool auto_update_bank_list();
void start_auto_update_timer();
void stop_auto_update_timer();
  • auto_update_bank_list() – update task invoked by the timer (documented as every 6 hours); returns a boolean typically used by GLib timers to continue or stop scheduling
  • start_auto_update_timer() – creates and stores the timer connection
  • stop_auto_update_timer() – disconnects auto_update_conn_ and stops scheduling

10. Settings Storage

void load_settings();
void save_settings();

Loads and persists page-specific settings (notably auto-update preferences) using:

~/.config/BastionGuard/settings.json

The settings file allows the page to restore user preferences at startup without requiring manual reconfiguration.

11. Helper Functions and Filesystem Layout

The header declares helper utilities used to locate data files, ensure directories exist, download remote resources, and normalize domains.

11.1 Path Helpers

static std::string user_data_dir();       // ~/.local/share/BastionGuard
static std::string banks_json_user();     // ~/.local/share/BastionGuard/banks.json
static std::string banks_json_system();   // /usr/share/BastionGuard/data/bank/banks.json
static std::string whitelist_json_user(); // ~/.local/share/BastionGuard/whitelist.json

These helpers define a two-tier model:

  • User scope – writable, per-user state under ~/.local/share/BastionGuard
  • System scope – read-only defaults under /usr/share/BastionGuard

11.2 Filesystem and Network Helpers

static bool        ensure_parent_dir(const std::string& path);
static bool        download_url_to_file(const std::string& url, const std::string& dest);
  • ensure_parent_dir() – ensures destination directory exists before writing files
  • download_url_to_file() – downloads a remote bank list to a local path (implementation-defined transport)

11.3 Domain Normalization

static std::string extract_domain(const std::string& url);
static std::string clean_domain(const std::string& d);

Utility functions used to normalize user input and bank list entries, typically by extracting the host from a URL and sanitizing it into a canonical domain representation for reliable comparison and storage.

11.4 System Installation Helper

void copy_banklist_to_system(const std::string& source_url);

Copies an updated bank list into the system location. This operation generally requires elevated privileges, and should be implemented with appropriate authorization prompts and safe, atomic install semantics.

12. Runtime and Security Considerations

  • Threading and timers: auto-update timers should execute without blocking the GTK main loop; network downloads must be asynchronous or offloaded to background threads.
  • Input validation: URL/domain normalization should reject malformed inputs and enforce a safe domain policy to avoid injection into configuration files.
  • Persistence safety: JSON writes should use an atomic write pattern (temporary file + rename) to reduce risk of corruption.
  • Privilege boundaries: copying data into /usr/share must be protected and audited; the UI should provide clear feedback on success/failure.
  • Transparency: status updates via lbl_status_ should include actionable messages when updates fail (network errors, parsing errors, permission issues).
Published on:
Last updated on: