Electron

Electron — desktop shell, typed IPC, hardening, signing

This skill owns the desktop shell: process model, IPC, security, packaging, signing, auto-update. It does not own the web UI inside the window (../react/SKILL.md), the Node backend logic, or the CI runner matrix.

The mental model — three processes, one rule

An Electron app is three kinds of process. Code lives in exactly one; putting it in the wrong one is the root cause of most security holes.

The governing rule: the renderer is untrusted, the main process holds all privilege, and the preload is the only sanctioned bridge between them. Renderer-to-OS escalation is the dominant failure mode in real Electron apps, so everything below is a corollary.

Start right

Scaffold with Electron Forge (@electron/forge) — first-party, all-in-one (scaffold → package → make → publish), and it gets new Electron features first.

bashCopy code
npm init electron-app@latest my-app -- --template=vite-typescript
cd my-app && npm start

Pin to a supported major. Electron ships a new major every 8 weeks (tracking Chromium) and supports only the latest 3 majors. As of June 2026 the stable line is Electron 42 (Chromium M148, Node 24); 43 lands 2026-06-30. Shipping on an EOL major means unpatched Chromium CVEs — check package.json and bump if behind.

Project layout keeps the boundary visible:

textCopy code
src/
  main.ts       # main process — owns everything privileged
  preload.ts    # the bridge — contextBridge only
  renderer/     # your web UI (untrusted)
  ipc/types.ts  # IPC contract shared by main + preload

The security baseline

Modern Electron defaults are already secure (nodeIntegration:false, contextIsolation:true, sandbox:true since Electron 20). Assert them explicitly anyway so a careless edit can't silently weaken the window:

tsCopy code
const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    nodeIntegration: false,        // renderer gets NO require/process — never flip true
    contextIsolation: true,        // preload + page run in separate JS worlds
    sandbox: true,                 // renderer in an OS sandbox; preload uses a limited API
    webSecurity: true,             // keep same-origin policy; never disable to "fix CORS"
    allowRunningInsecureContent: false, // no mixed http content on https pages
  },
});

One why per flag: each removes a documented way for renderer-side script to reach Node or the OS. Flipping any of them to the insecure value is what verify.sh fails on.

CSP via response headers, not a <meta> tag — meta CSP can't restrict the initial document and is trivially bypassed for some directives. Set it in the main process:

tsCopy code
session.defaultSession.webRequest.onHeadersReceived((details, cb) => {
  cb({ responseHeaders: { ...details.responseHeaders,
    'Content-Security-Policy': ["default-src 'self'; script-src 'self'"] } });
});

Lock navigation. A renderer that can navigate to attacker content gets the renderer's privileges. Deny unexpected navigation and block new windows:

tsCopy code
app.on('web-contents-created', (_e, contents) => {
  contents.on('will-navigate', (e, url) => {
    if (new URL(url).origin !== 'https://app.local') e.preventDefault();
  });
  contents.setWindowOpenHandler(() => ({ action: 'deny' })); // no tab-jacking
});

Open real external links deliberately, after allow-listing the protocol:

tsCopy code
function openExternal(url: string) {
  const { protocol } = new URL(url);
  if (protocol === 'https:' || protocol === 'mailto:') shell.openExternal(url);
}

Which branch are you on?

• Local-only UI (you bundle the HTML/JS): CSP + sandbox:true + nav lockdown is enough.
• Loads any remote/third-party content: also add Electron Fuses (disable run-as-node, encrypt cookies, ASAR integrity) and treat every embedded origin as hostile.

Fuses and the full hardened example live in references/security-and-ipc.md.

Typed IPC the right way

IPC is the seam between untrusted renderer and privileged main. Get it wrong and you've handed the OS to whatever script runs in the page.

Never expose ipcRenderer (or any of its methods) across the bridge. Sending the whole module now yields an empty object on the other side — a deliberate footgun removal — and exposing its methods lets the page call any channel with any payload.

tsCopy code
// Bad — preload.ts: hands the renderer a universal IPC weapon (also: empty object now)
contextBridge.exposeInMainWorld('api', ipcRenderer);

tsCopy code
// Good — preload.ts: ONE function per channel, each wrapping a specific call
import { contextBridge, ipcRenderer } from 'electron';
contextBridge.exposeInMainWorld('api', {
  readConfig: () => ipcRenderer.invoke('config:read'),
  saveNote: (text: string) => ipcRenderer.invoke('note:save', text),
  onSync: (cb: () => void) => ipcRenderer.on('sync:done', cb), // events: send/on
});

Prefer ipcMain.handle + ipcRenderer.invoke (request/response, returns a Promise) for anything that returns data. Reserve send/on for fire-and-forget events (progress, push notifications). Validate every argument in main — a renderer message is an HTTP request from an untrusted client:

tsCopy code
ipcMain.handle('note:save', (_e, text: unknown) => {
  if (typeof text !== 'string' || text.length > 10_000) throw new Error('bad input');
  return saveNote(text); // never path.join(userInput) or eval it
});

Share the contract as TypeScript types across both sides (ipc/types.ts) so a channel rename breaks the build, not production. Full main + preload + window.api d.ts example: references/security-and-ipc.md.

Native capabilities — renderer asks, main acts

The renderer can't (and must not) touch the OS directly. When the UI needs a native menu, tray icon, file dialog, system notification, custom protocol:// handler, or a child_process, the renderer invokes an IPC channel and the main process performs the action and returns a result. Same one-function-per-channel discipline as above.

For embedding web content in a region of a window, use WebContentsView — BrowserView is deprecated since Electron 30. They share shape (both take webPreferences; setBounds/getBounds/webContents carry over), so migration is mechanical.

Packaging, signing, auto-update

Two real toolchains:

Code signing is a prerequisite for auto-update, not optional polish. macOS auto-update (Squirrel.Mac) refuses to update an app that isn't signed and notarized; Windows updates need an Authenticode-signed installer. So the order is always: sign → notarize → publish → auto-update. Full Forge and builder configs, notarytool steps, Windows Authenticode, and electron-updater + GitHub Releases wiring: references/packaging-and-updates.md.

The CI matrix that runs these builds across three OSes is github-actions' job; this skill defines what to build and sign.

Anti-patterns and migration smells

Verify

Run scripts/verify.sh /path/to/your-electron-project to grep a target for insecure patterns (nodeIntegration: true, contextIsolation: false, sandbox: false, @electron/remote, new BrowserView, exposeInMainWorld(..., ipcRenderer)). It's read-only and exits non-zero on any finding. With no argument it self-checks this skill's own example snippets for the secure baseline. See references/security-and-ipc.md for the full checklist.