LeakCheckProvider (Identity Leak)

1. Overview

The LeakCheckProvider module implements an Identity Leak provider backed by the LeakCheck Public API. It serves as an always-available fallback data source in BastionGuard’s Identity Leak subsystem, particularly when premium providers (e.g., HIBP) are not configured or temporarily unavailable.

The provider:

  • Queries the LeakCheck public endpoint using an email address
  • Parses JSON responses and maps findings into LeakRecord
  • Returns an empty result set on network errors, parse failures, or “not found” responses
  • Assigns a fixed severity and minimal data classification due to limited public API detail

2. Dependencies

  • HttpClient – HTTPS transport and URL encoding
  • nlohmann/json – JSON parsing
  • glib/gi18n – localized UI description string via _()

3. Email Lookup Flow

3.1 Input Preconditions

If the email is empty, the provider returns an empty result set immediately. No network activity occurs.

3.2 Endpoint

The provider queries the LeakCheck public API endpoint:

https://leakcheck.io/api/public?check=<urlencoded_email>

The email value is URL-encoded using:

HttpClient::urlEncode(email)

3.3 Request Execution

The request is executed as an HTTP GET with:

  • No custom headers (empty header map)
  • Timeout of 15 seconds
HttpResponse resp = HttpClient::get(url, {}, 15);

4. HTTP and JSON Error Handling

4.1 HTTP Status Handling

If the HTTP response status is not 200, the provider returns an empty result set.

This “fail-closed” behavior prevents the UI from reporting uncertain data when the endpoint is unavailable or rate-limited.

4.2 JSON Parse Handling

The provider attempts to parse the response body as JSON. If parsing fails, it returns an empty result set.

No exception is propagated; this provider is designed to be non-fatal within aggregated workflows.

4.3 Found Flag

The provider checks the boolean field:

found

If found is false (or missing), the provider returns an empty result set.

5. Mapping to LeakRecord

5.1 Sources Enumeration

If found is true, the provider enumerates:

root["sources"]

Each element is treated as a source identifier string and becomes a separate LeakRecord entry.

5.2 Record Fields

For each source entry:

  • provider: "LeakCheck (public)"
  • breachName: the source string value
  • breachDate: empty string (not available via public endpoint)
  • description: localized label indicating the origin is the LeakCheck Public API
  • severity: fixed LeakRecord::Severity::MEDIUM
  • dataClasses: fixed list containing "Email address"

Records are appended to the result vector using move semantics.

6. Output Semantics

The provider returns:

  • An empty vector if:
    • Email is empty
    • HTTP status is not 200
    • JSON parsing fails
    • found is false
  • A vector of one or more LeakRecord entries if:
    • found is true and sources contains entries

Because the public API provides limited context, severity and data classes are conservative defaults and should be interpreted as “exposure indication,” not as a full breach intelligence report.

7. Runtime and Security Considerations

  • Privacy: the email address is transmitted to a third-party service (LeakCheck). This should be controlled by user consent and aligned with privacy policy
  • Non-fatal integration: the provider returns empty results rather than throwing exceptions, making it safe as a fallback provider in aggregated execution
  • Limited fidelity: breach dates and detailed data classes are not available from the public endpoint; the UI should communicate that these are partial results
  • Transport security: HTTPS requests rely on HttpClient, which keeps TLS verification enabled
  • Timeout discipline: a 15-second timeout prevents long stalls in UI or monitoring threads
  • Future extensibility: if LeakCheck introduces richer fields, the mapping can be expanded to populate breach dates, descriptions, and data classes more accurately
Published on:
Last updated on: