Electron Apps skill for Codex

Done well means: the renderer is treated as an untrusted web page, it reaches the system only through a small, typed, validated preload API, the app stays on a supported Electron major, and installers update themselves from a signed release feed.

Before changing anything

1. Read AGENTS.md, package.json and the build config (forge.config.*, electron-builder.yml or the build key) to learn the toolchain and bundler (Vite, webpack, esbuild).
2. Find the main entry ("main" in package.json), every new BrowserWindow, every preload script and every ipcMain handler.
3. Run the scanner: node scripts/audit-electron-security.mjs . and read every HIGH.
4. Check the Electron version against the release schedule. Electron ships a major every 8 weeks and supports the latest three; an unsupported major gets no Chromium security fixes, so plan the upgrade before feature work.
5. npm install and Electron’s binary download need network; request approval in a sandboxed Codex session.

Process model

Process	Runs	May use
Main	Node.js, one per app	Everything: fs, child processes, native modules, OS APIs
Preload	Isolated world before page scripts	contextBridge, ipcRenderer; Node APIs are limited when sandboxed
Renderer	Chromium page, sandboxed	DOM and the API the preload exposes, nothing else
Utility process	utilityProcess.fork()	Node work off the main thread (CPU work, crash-prone libs)

Never block the main process: synchronous fs on large files, execSync, or CPU loops freeze every window. Move heavy work to a utility process or worker.

Window defaults

const win = new BrowserWindow({
  width: 1100, height: 720, show: false,
  webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    contextIsolation: true,   // default, keep it
    sandbox: true,            // default for renderers, keep it
    nodeIntegration: false,   // default, keep it
    webSecurity: true,
  },
});
win.once('ready-to-show', () => win.show());

win.webContents.setWindowOpenHandler(({ url }) => {
  if (isAllowedExternal(url)) shell.openExternal(url);
  return { action: 'deny' };
});
win.webContents.on('will-navigate', (event, url) => {
  if (new URL(url).origin !== APP_ORIGIN) event.preventDefault();
});
session.defaultSession.setPermissionRequestHandler((_wc, permission, cb) => cb(permission === 'clipboard-sanitized-write'));

isAllowedExternal permits only https: (and mailto: if needed) to known hosts. shell.openExternal with an attacker-controlled URL can launch arbitrary protocol handlers.

IPC through the preload

Expose functions, not ipcRenderer. One channel per operation, invoke/handle for request-response.

// preload.ts
import { contextBridge, ipcRenderer } from 'electron';
contextBridge.exposeInMainWorld('api', {
  readNote: (id: string) => ipcRenderer.invoke('note:read', id),
  onSyncStatus: (cb: (s: string) => void) => {
    const listener = (_e: unknown, s: string) => cb(s);
    ipcRenderer.on('sync:status', listener);
    return () => ipcRenderer.removeListener('sync:status', listener);
  },
});

// main.ts
ipcMain.handle('note:read', async (event, id: unknown) => {
  if (!isTrustedFrame(event.senderFrame)) throw new Error('untrusted sender');
  if (typeof id !== 'string' || !/^[a-z0-9-]{1,64}$/.test(id)) throw new Error('bad id');
  return notes.read(id);                 // never pass a raw path from the renderer to fs
});

• Validate the sender (event.senderFrame.url origin) and every argument in main; the renderer can call any exposed channel with any value.
• Do not forward the IPC event object to the renderer, and do not offer generic “run this command” or “read this path” channels.
• Share channel names and payload types in one TypeScript module imported by preload, main and the renderer’s window.api declaration.

Loading content

• Serve app files through a custom protocol registered with protocol.handle('app', ...) and protocol.registerSchemesAsPrivileged, rather than file://, so CSP and origin checks work. Resolve paths and refuse anything outside the app directory.
• Set a strict CSP (meta tag or response header): default-src 'self'; script-src 'self' and no unsafe-eval. Bundlers in dev mode may need a looser dev-only policy.
• Never load remote web content into a window that has a preload with powerful APIs. Show remote pages in a separate window or WebContentsView with no preload.

Fuses

Flip fuses at package time (Forge @electron-forge/plugin-fuses or @electron/fuses): RunAsNode off, EnableNodeOptionsEnvironmentVariable off, EnableNodeCliInspectArguments off, EnableEmbeddedAsarIntegrityValidation on, OnlyLoadAppFromAsar on, EnableCookieEncryption on. These stop the shipped binary from being reused as a signed Node.js runtime.

Packaging and updates

Need	Default
New project, official tooling	Electron Forge (npm init electron-app@latest app -- --template=vite-typescript)
Existing electron-builder setup, NSIS/AppImage/differential updates	Keep electron-builder + electron-updater
Public GitHub repo, simple updates	update-electron-app with update.electronjs.org
Private feed	Forge publisher to S3 or a static server; electron-builder generic provider

• Native modules must be rebuilt against Electron’s Node ABI; Forge does this, otherwise run npx @electron/rebuild. Mark them asarUnpack if they load files at runtime.
• macOS auto-update requires a signed and notarized app; Windows needs a signed installer for SmartScreen. Signing, notarization and release channels are covered by desktop-app-distribution.
• Publishing a release to the update feed reaches every installed user: confirm the version and channel with the user before running publish.
• Use app.requestSingleInstanceLock() and route second-instance arguments (deep links, files) to the existing window.

Upgrading Electron

1. Read the breaking changes doc for every major you cross.
2. Bump electron and rebuild native modules; run the app and tests.
3. Re-run the scanner and check deprecated APIs (BrowserView gave way to WebContentsView; old protocol.register*Protocol to protocol.handle).

Gotchas

• Disabling sandbox to make a preload require a Node module is the most common regression; move that code to main behind IPC instead.
• webContents.executeJavaScript with interpolated strings is code injection.
• Auto-update on Windows with Squirrel runs the app with --squirrel-* flags on install; handle them (electron-squirrel-startup) or the app launches during install.
• macOS Info.plist usage strings (camera, microphone) are required or the app is killed on first access.
• Dev-only flags (ELECTRON_DISABLE_SECURITY_WARNINGS, DevTools auto-open) must not ship.

Verification

1. node scripts/audit-electron-security.mjs . exits 0, and each MEDIUM is either fixed or explained.
2. Electron’s own security warnings in the DevTools console are gone in a dev build.
3. In the packaged app, window.require, process and ipcRenderer are undefined in the renderer console.
4. Install version N, publish N+1 to a test channel, and confirm the update downloads, applies and relaunches on each OS.

Output

**Electron:** <version> (supported: yes/no) **Tooling:** Forge | electron-builder
**Security:** scanner high/medium counts before -> after; fuses set
**IPC surface:** <channel -> purpose, validation>
**Updates:** <provider, channel, tested on macOS/Windows/Linux>