/desktop-security-electron

name: desktop-security-electron
description: Electron fuses, ASAR integrity, sandbox hardening, CSP, permission handling, navigation restrictions

Electron Security & Fuses

> **Quick Guide:** Electron fuses are compile-time security flags flipped via `@electron/fuses` before code signing. Disable `RunAsNode`, `EnableNodeOptionsEnvironmentVariable`, `EnableNodeCliInspectArguments`, and `GrantFileProtocolExtraPrivileges`. Enable `EnableCookieEncryption`, `EnableEmbeddedAsarIntegrityValidation`, and `OnlyLoadAppFromAsar`. Rely on secure defaults: `contextIsolation: true` (Electron 12+), `sandbox: true` (Electron 20+), `nodeIntegration: false` (Electron 5+). Set a restrictive Content Security Policy. Use `setPermissionRequestHandler` to deny all permissions except an explicit allowlist. Block navigation and new-window creation.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST flip fuses BEFORE code signing -- the OS enforces fuse state after signing, so flipping after signing invalidates the signature)**

**(You MUST disable `RunAsNode`, `EnableNodeOptionsEnvironmentVariable`, `EnableNodeCliInspectArguments`, and `GrantFileProtocolExtraPrivileges` fuses in production builds -- these are the most commonly exploited attack vectors)**

**(You MUST enable both `EnableEmbeddedAsarIntegrityValidation` AND `OnlyLoadAppFromAsar` together -- enabling integrity validation alone still allows bypassing via the app code search path)**

**(You MUST NOT override security defaults (`contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`) -- each one unlocks a critical attack surface)**

**(You MUST restrict permissions via `session.setPermissionRequestHandler()` -- Electron grants most permissions by default, including camera, microphone, and geolocation)**

</critical_requirements>

---

**Auto-detection:** Electron fuses, @electron/fuses, FuseV1Options, FuseVersion, flipFuses, RunAsNode, EnableCookieEncryption, EnableEmbeddedAsarIntegrityValidation, OnlyLoadAppFromAsar, GrantFileProtocolExtraPrivileges, ASAR integrity, Electron security, contextIsolation, sandbox, nodeIntegration, webPreferences security, Content-Security-Policy, setPermissionRequestHandler, setPermissionCheckHandler, will-navigate, setWindowOpenHandler, shell.openExternal validation, deep link validation, registerSchemesAsPrivileged, ELECTRON_RUN_AS_NODE, NODE_OPTIONS

**When to use:**

• Configuring Electron fuses for production builds
• Setting up ASAR integrity validation
• Hardening webPreferences and sandbox settings
• Defining Content Security Policy for renderer HTML
• Restricting permissions, navigation, and new-window creation
• Validating deep link / custom protocol URLs
• Securing `shell.openExternal()` calls
• Auditing an Electron app's security posture

**When NOT to use:**

• General Electron architecture (main/renderer process model, IPC patterns, app lifecycle)
• Packaging and distribution (Electron Forge, Electron Builder setup)
• Native OS API integration (dialogs, menus, tray, notifications)
• Choosing a UI framework for the renderer window

**Key patterns covered:**

• Fuse configuration with `@electron/fuses` (all 9 fuses explained)
• ASAR integrity validation (macOS + Windows, required fuses, tooling support)
• Secure webPreferences defaults and audit pattern
• Content Security Policy (meta tag and session headers)
• Permission request/check handlers with allowlists
• Navigation and new-window restriction
• `shell.openExternal()` URL validation
• Custom protocol security and deep link validation
• `file://` protocol replacement with custom schemes

---

<philosophy>

Philosophy

Electron security follows a **defense-in-depth** strategy: multiple independent layers each reduce attack surface, so a breach in one layer does not compromise the entire app.

The layers from outermost to innermost:

1. **Fuses** -- compile-time flags that remove features from the binary entirely (cannot be re-enabled at runtime) 2. **ASAR integrity** -- ensures packaged app code has not been tampered with 3. **Process sandbox** -- OS-level isolation restricting what renderer processes can access 4. **Context isolation** -- separates preload script scope from renderer globals 5. **Content Security Policy** -- restricts what the renderer can load and execute 6. **Permission handlers** -- explicit allowlist for web API permissions 7. **Navigation restrictions** -- prevent renderers from leaving the app's origin 8. **Input validation** -- treat all IPC messages and URLs as untrusted

**Key principle:** Never rely on a single security mechanism. Each layer handles a different class of attack. Fuses stop living-off-the-land attacks. Sandboxing stops renderer-to-OS escalation. CSP stops code injection. Permission handlers stop unauthorized API access.

**When to use this skill:**

• Preparing an Electron app for production distribution
• Responding to a security audit or penetration test
• Configuring build tooling to flip fuses and enable ASAR integrity
• Reviewing webPreferences, CSP, and permission handling

**When NOT to use:**

• Initial app scaffolding (set up the app first, then harden)
• Debugging IPC or window management (not a security concern)
• Styling or UI framework decisions

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Fuse Configuration

Fuses are compile-time feature toggles embedded in the Electron binary. Once flipped and code-signed, the OS prevents reversal. Use the `@electron/fuses` package to flip them during your build step.

// build-scripts/flip-fuses.js
const { flipFuses, FuseVersion, FuseV1Options } = require("@electron/fuses");

await flipFuses(
  // Path to your packaged Electron binary
  require("electron"),
  {
    version: FuseVersion.V1,
    [FuseV1Options.RunAsNode]: false,
    [FuseV1