LeakDatabase.hpp

1. Overview

The LeakDatabase.hpp header defines the LeakDatabase class, which provides a persistent storage layer for identity breach records detected by BastionGuard.

This component is responsible for tracking previously discovered leaks per monitored identity and preventing duplicate notifications.

Functionally, LeakDatabase provides:

  • Persistent storage of breach events
  • Per-identity leak history tracking
  • Detection of newly discovered breaches
  • SQLite-backed local database management
  • Thread-safe access serialization
  • Support for privacy-preserving identity hashing

2. Dependencies and Includes

#include "../model/LeakRecord.hpp"
#include <string>
#include <mutex>
  • LeakRecord.hpp – standardized breach data model
  • <string> – identity hashes and file paths
  • <mutex> – thread synchronization primitives

3. Class Declaration and Scope

class LeakDatabase

The class encapsulates a lightweight embedded database (SQLite) and exposes high-level persistence operations.

It is designed for concurrent use by monitoring and aggregation components.

4. Public Interface

4.1 Constructor

LeakDatabase();

Initializes the database instance and prepares the underlying storage backend.

4.2 Identity Registration

void ensureIdentity(const std::string& emailHash);

Registers a monitored identity in the database.

  • emailHash – hashed representation of the email address

If the identity already exists, this operation is idempotent.

4.3 New Leak Detection

bool isNewLeak(const std::string& emailHash,
               const LeakRecord& record);

Determines whether a breach record has already been stored for the given identity.

  • emailHash – hashed identity key
  • record – breach record to be evaluated
  • Return value – true if the breach is new

This method is used to suppress duplicate alerts.

4.4 Leak Persistence

void storeLeak(const std::string& emailHash,
               const LeakRecord& record);

Persists a newly detected breach record for the specified identity.

Callers are expected to invoke isNewLeak() prior to storing records.

5. Internal State and Data Model

std::string dbPath;
void* db; // sqlite3*
std::mutex dbMutex;
  • dbPath – filesystem path of the SQLite database file
  • db – opaque handle to the SQLite connection
  • dbMutex – mutual exclusion lock for concurrent access

6. Internal Initialization Logic

6.1 Database Opening

void open();

Opens (or creates) the SQLite database file and initializes the connection handle.

6.2 Schema Initialization

void initSchema();

Creates the required tables and indexes if they do not already exist.

The schema typically includes:

  • Identity table (hashed email)
  • Breach metadata table
  • Uniqueness constraints
  • Timestamp columns

7. Concurrency Model

LeakDatabase serializes all database operations using an internal mutex.

  • Prevents simultaneous writes
  • Protects SQLite connection state
  • Ensures transactional consistency
  • Avoids race conditions in multi-threaded monitors

8. Integration with Monitoring Pipeline

LeakDatabase is typically used by:

  • LeakMonitor for stateful breach tracking
  • LeakAggregator for deduplication
  • Notification dispatchers
  • Audit and reporting modules

9. Data Retention and Lifecycle

Stored breach records persist across application restarts.

Retention policies may include:

  • User-initiated deletion
  • Automatic pruning after retention periods
  • Database reset on user request

10. Privacy and Compliance Considerations

  • Identity hashing: plaintext emails are never stored.
  • Local-only storage: data is kept on the user’s device.
  • Encryption at rest: may be applied at the filesystem or database layer if required.
  • Regulatory compliance: storage policies should align with GDPR and similar regulations.

11. Performance Considerations

  • Indexing: identity and breach identifiers should be indexed for fast lookups.
  • Batching: multiple inserts may be grouped into transactions.
  • Connection reuse: a single persistent handle minimizes overhead.
  • Disk I/O: database location should be placed on reliable storage.

12. Runtime and Security Considerations

  • Crash resilience: SQLite journaling should be enabled to prevent corruption.
  • Backup strategy: periodic database backups may be advisable.
  • Error handling: SQL failures must be logged and surfaced appropriately.
  • Schema migration: future versions should support safe upgrades.
  • Resource cleanup: database handles must be closed on shutdown.
Published on:
Last updated on: