xdg-open.hpp

1. Overview

The xdg-open.hpp header defines the BankOpener utility class, a security-oriented access control layer responsible for conditionally opening external URLs only when they belong to trusted banking domains or approved payment service providers.

This component acts as a gatekeeper between BastionGuard and the system’s default URL handler (xdg-open or equivalent), preventing untrusted or potentially malicious domains from being opened automatically.

Functionally, BankOpener provides:

  • Validation of URLs before opening them in external browsers
  • Extraction and normalization of domain names
  • Verification against trusted banking domain lists
  • Optional validation against approved payment providers
  • Protection against phishing and redirect-based attacks
  • Centralized enforcement of secure browsing policies

2. Dependencies and Includes

#include <string>
  • <string> – URL parsing, domain normalization, and comparison

3. Class Declaration and Scope

class BankOpener

The class is implemented as a static utility container. All methods are static, and no instances are intended to be created.

Despite the filename (xdg-open.hpp), the class abstracts away direct interaction with xdg-open, exposing a policy-based interface for controlled URL launching.

4. Public Interface

4.1 Conditional URL Opener

static bool open_if_trusted(const std::string& url);

Evaluates the given URL and opens it using the system’s default handler only if the target domain satisfies configured trust policies.

  • url – target URL to be opened
  • Return value – true if the URL was accepted and launched, false if it was rejected

Rejected URLs are typically logged or surfaced to the user through notification mechanisms.

5. UI Components

This component does not define graphical UI elements. It operates as a backend policy and enforcement layer invoked by UI pages (e.g., secure payments, banking, or phishing protection workflows).

6. Internal State and Data Model

No persistent state is stored in this class. All trust evaluation is performed dynamically using external configuration and domain lists managed by other subsystems.

7. Helper Functions

The following private helpers implement URL parsing and trust validation:

static std::string extract_domain(const std::string& url);
static bool is_trusted_domain(const std::string& domain);
static bool is_payment_domain(const std::string& domain);
static std::string clean_domain(const std::string& d);
static bool ends_with(const std::string& value,
                      const std::string& suffix);
  • extract_domain() – extracts the hostname from a URL
  • is_trusted_domain() – verifies membership in the trusted bank list
  • is_payment_domain() – checks whether the domain belongs to approved payment providers
  • clean_domain() – normalizes domains (lowercase, trimming, canonical form)
  • ends_with() – helper for suffix matching (subdomain handling)

8. Internal Logic

A typical open_if_trusted() workflow includes:

  • Parsing and validating the input URL
  • Extracting the hostname component
  • Normalizing the domain string
  • Comparing against trusted bank lists
  • Optionally comparing against payment provider lists
  • Invoking the system URL handler if validation succeeds

9. Integration with Secure Payments and Banking

BankOpener is typically used in conjunction with:

  • BankPage (bank domain management)
  • SettingsStore (payment domains configuration)
  • SecureBrowser (embedded secure browsing)
  • Phishing and anti-fraud subsystems

Depending on configuration, validated URLs may be opened either in an embedded secure browser or via the system browser.

10. Settings Storage

This class does not manage persistence directly. Trusted and payment domains are retrieved from external configuration sources, typically:

  • User-managed JSON lists (e.g., payments.json, bank lists)
  • System-provided default domain lists
  • Central settings stores

11. Helper Functions and Platform Integration

On Linux systems, accepted URLs are usually opened via xdg-open or an equivalent desktop handler. Other platforms may use native APIs.

This abstraction ensures that platform-specific launching logic remains isolated from security policy enforcement.

12. Runtime and Security Considerations

  • Phishing resistance: strict domain normalization and suffix matching should be used to prevent homograph and subdomain attacks.
  • Redirect handling: URLs that redirect to untrusted domains should be revalidated after resolution.
  • Configuration trust: system-provided domain lists must be integrity-protected and verified.
  • Fail-closed policy: when validation fails, URLs should be rejected by default.
  • User feedback: rejected URLs should trigger clear notifications explaining the reason for blocking.
  • Logging: rejected and accepted attempts should be logged for auditing and troubleshooting.
Published on:
Last updated on: