Skip to content

4.2 Security Allowlist CSP and Preload Bridge

Jump to bottom
coding man edited this page Nov 4, 2026 · 1 revision

Security: Allowlist, CSP and Preload Bridge

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This page documents the security architecture of the VariantScope desktop application, focusing on host enforcement via allowlists, Content Security Policy (CSP) generation, and the sandboxed preload bridge that safely exposes Main Process capabilities to the Renderer Process via context isolation.

Sources: electron/allowlist.js:1-49, electron/csp.js:1-25, electron/preload.cjs:1-70

1. URL Allowlist and Validation (electron/allowlist.js)

VariantScope enforces strict boundary controls on all outbound network connections and system-level hyperlink openings. The allowlist module (electron/allowlist.js) defines permissible target domains and implements validation helpers electron/allowlist.js:1-48.

API Hosts and External Links

The module maintains two distinct sets of frozen host arrays:

  • API_HOSTS: Restricts backend queries initiated via fetch abstractions to verified bioinformatics APIs over HTTPS (rest.uniprot.org, alphafold.ebi.ac.uk, eutils.ncbi.nlm.nih.gov, gnomad.broadinstitute.org) electron/allowlist.js:4-9.
  • LINK_HOSTS: Extends API_HOSTS to include documentation and portal destinations (www.uniprot.org, www.ncbi.nlm.nih.gov, github.com) permitted for system browser navigation electron/allowlist.js:12-17.

Validation Functions

  • parseHttps(raw): Parses string input into a URL instance, enforcing that the protocol is strictly https:, rejects credentials (username or password), and disallows non-standard ports electron/allowlist.js:19-32.
  • checkApiUrl(raw): Evaluates a target API request URL, returning { ok: true, url } upon success or an error object if the host or protocol fails validation electron/allowlist.js:35-42.
  • isAllowedExternalLink(raw): Validates links targeted for external system browser execution electron/allowlist.js:45-48.

Diagram: URL Allowlist and Validation Flow

graph TD
    A["Raw Input String"] --> B["parseHttps(raw)"]
    B --> C{"Valid HTTPS URL?"}
    C -->|No| D["Return {ok: false, error}"]
    C -->|Yes| E{"API_HOSTS Match?"}
    E -->|No| F["Return Blocked Error"]
    E -->|Yes| G["Return {ok: true, url}"]
    
    sub_CodeEntities["Code Entities"]
    sub_CodeEntities --- H["electron/allowlist.js: checkApiUrl()"]
    sub_CodeEntities --- I["electron/allowlist.js: API_HOSTS"]
    sub_CodeEntities --- J["electron/allowlist.js: parseHttps()"]
Loading

Sources: electron/allowlist.js:1-49, tests/unit/allowlist.test.js:1-43

2. Content Security Policy (electron/csp.js)

Content Security Policies (CSPs) mitigate cross-site scripting (XSS) and injection vectors by restricting resource loading and network execution contexts electron/csp.js:1-25.

CSP Targets

The buildCsp(target) function constructs policy strings tailored to three distinct execution targets electron/csp.js:5-25:

  1. 'electron': Sets connect-src 'none', completely blocking direct renderer-initiated network calls and forcing all data fetching through the secure IPC preload bridge electron/csp.js:6-7.
  2. 'web': Allows connections to API_HOSTS for browser/web deployment environments electron/csp.js:8.
  3. 'dev': Permits local websocket connections (ws://localhost:5173) and inline styling ('unsafe-inline') to support Vite hot module reloading during local development electron/csp.js:9-16.

Sources: electron/csp.js:1-25

3. The Preload Bridge and Context Isolation (electron/preload.cjs)

Electron's security model runs the renderer in a sandboxed, context-isolated environment. electron/preload.cjs acts as the exclusive gatekeeper between the renderer and Node.js/Electron main process APIs electron/preload.cjs:1-69.

Context Isolation & window.api

Using contextBridge.exposeInMainWorld(), the preload script exposes exactly six validated functions under the window.api namespace electron/preload.cjs:1-12.

  1. fetchJson(url, options): Proxies API requests through the main process cache and allowlist gatekeeper, bypassing CORS restrictions electron/preload.cjs:14-32.
  2. saveFile(kind, suggestedName, data): Triggers native save dialogs for CSV exports or PNG visualizations electron/preload.cjs:35-42.
  3. openExternal(url): Requests the main process to open an allowlisted URL in the external system browser electron/preload.cjs:44-48.
  4. listCache(): Queries stored gene payloads and sizes from the disk cache electron/preload.cjs:50-53.
  5. deleteCache(target): Purges specified gene cache entries or clears all stored assets electron/preload.cjs:55-63.
  6. getAppInfo(): Retrieves application metadata (version, platform, architecture) for the About modal electron/preload.cjs:65-68.

Input Validation

All parameters entering the bridge undergo rigorous type checking via requireString() to ensure strings are non-empty and bounded within safety limits (e.g., maximum URL length of 4096 characters, bodies capped at 1,000,000 bytes) electron/preload.cjs:5-10.

Diagram: IPC Bridge Data Flow and Code Space Mapping

graph TD
    A["Renderer Process (src/core/http.js)"] -->|window.api.fetchJson| B["Preload Bridge (electron/preload.cjs)"]
    B -->|requireString validation| C["ipcRenderer.invoke('fetch-json')"]
    C -->|IPC Message| D["Main Process (electron/fetcher.js)"]
    D -->|checkApiUrl| E["Disk Cache / HTTPS Fetch"]
    E -->|Result Payload| C
    C -->|Resolved Promise| A
    
    sub_BridgeFunctions["Exposed Methods on window.api"]
    sub_BridgeFunctions --- F["fetchJson()"]
    sub_BridgeFunctions --- G["saveFile()"]
    sub_BridgeFunctions --- H["openExternal()"]
    sub_BridgeFunctions --- I["listCache()"]
    sub_BridgeFunctions --- J["deleteCache()"]
    sub_BridgeFunctions --- K["getAppInfo()"]
Loading

Sources: electron/preload.cjs:1-70, src/core/http.js:35-51

Content imported from DeepWiki.

VariantScope Wiki

Clone this wiki locally