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.

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:

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:

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:

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:

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:

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.

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

// 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:

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.