BastionGuard-secure.hpp

1. Overview

The BastionGuard-secure.hpp header defines the SecureList class, responsible for controlling how sensitive web resources—particularly payment-related domains—are opened within the BastionGuard ecosystem. This component determines whether a given URL should be handled by the internal SecureBrowser or delegated to the system default browser, based on a configurable allowlist.

Functionally, SecureList provides:

  • Policy-based decision making for secure URL handling
  • Domain validation against a persistent payments allowlist
  • Automatic routing to SecureBrowser or system browser
  • Domain normalization and comparison utilities
  • Cached access to trusted domain configuration

2. Dependencies and Includes

#include <string>
#include <vector>
  • <string> – storage and processing of URLs and domain names
  • <vector> – in-memory cache of trusted payment domains

3. Class Declaration and Scope

class SecureList

The SecureList class is implemented as a static policy controller. It does not require instantiation and exposes all functionality through static member functions.

4. Public Interface

4.1 Secure Open Decision

static bool open_if_allowed(const std::string& url,
                            int argc,
                            char** argv);

Evaluates the specified URL against the configured payments allowlist and decides whether it should be opened in the internal SecureBrowser or in the system default browser.

Returns true if the URL is handled internally, otherwise false.

4.2 Payment Domain Verification

static bool is_payment_domain(const std::string& domain);

Determines whether the specified domain, or one of its parent domains, is listed in the payments configuration file (payments.json).

4.3 Domain Utility Functions

static std::string extract_domain(const std::string& url);
static std::string clean_domain(const std::string& d);
static bool ends_with(const std::string& s,
                      const std::string& suffix);

Provides helper functions for extracting, normalizing, and comparing domain names in a consistent and secure manner.

5. Private Infrastructure

5.1 Payments Configuration Path

static std::string config_path_payments();

Resolves the absolute filesystem path of the payments.json configuration file, typically located under the BastionGuard user configuration directory.

5.2 System Browser Integration

static void open_system_browser(const std::string& url);

Launches the system default web browser to open the specified URL when internal handling is not required or permitted.

5.3 Payments Cache Accessor

static const std::vector<std::string>& payments_cache_only();

Provides read-only access to the in-memory cache of trusted payment domains. The cache is lazily loaded and reused to minimize filesystem access.

6. Decision Logic and Processing Flow

The secure opening workflow typically follows these steps:

  • Extract and normalize the domain from the input URL
  • Compare the domain and its parent domains against the cached allowlist
  • If matched, invoke the SecureBrowser subsystem
  • Otherwise, delegate handling to the system browser
  • Return the execution result to the caller

7. Configuration Model

The payments configuration file generally contains:

  • Trusted payment and banking domains
  • Optional metadata for classification and auditing
  • Versioning or schema identifiers

8. Security and Compliance Considerations

  • Domain canonicalization: all domains must be normalized to prevent bypass via subdomain or encoding tricks
  • Configuration integrity: payments.json should be protected against unauthorized modification
  • Browser isolation: SecureBrowser should enforce sandboxing, certificate validation, and hardened runtime policies
  • URL validation: inputs should be checked for unsupported schemes or malformed structures
  • Auditability: security-relevant routing decisions should be logged for forensic and compliance purposes
  • Fail-safe defaults: in ambiguous cases, URLs should default to the secure handling path rather than unrestricted opening
Published on:
Last updated on: