Electron desktop app rules

# AGENTS.md: Electron desktop app

Electron app: a privileged main process (Node.js) and renderer processes that show web content. Treat every renderer
as untrusted web content, even when it only loads your own bundle. Follow the Electron security checklist.

## Commands
- Check the project's `package.json` scripts first. Typical: `npm start` (dev), `npm test`, `npm run make` or
  `npm run dist` (packaging).
- Type-check with `npx tsc --noEmit` if the project uses TypeScript.
- Before finishing, run the `electron-ipc-channel` skill's security check (`scripts/check_electron_security.mjs` in the
  skill folder) over `src/`. It must report no findings.

## Windows (BrowserWindow and webPreferences)
- Keep the secure defaults and write them out so reviews can see them: `contextIsolation: true`, `sandbox: true`,
  `nodeIntegration: false`. Never set `webSecurity: false`, `allowRunningInsecureContent: true`,
  `experimentalFeatures: true` or `enableBlinkFeatures`.
- Load local pages from a custom protocol (`protocol.handle`) or the packaged file, never remote code into a window
  with a preload.
- Set `webContents.setWindowOpenHandler` to deny by default and open allowed links with `shell.openExternal` only
  after checking the URL scheme is `https:` (or a small allow-list).
- Handle `will-navigate` and block navigation away from the app's origin.
- Define a Content Security Policy (meta tag or response header): `default-src 'self'`, no `unsafe-eval`.

## Preload and IPC
- The preload exposes small, named functions through `contextBridge.exposeInMainWorld`. Never expose `ipcRenderer`,
  `require`, `process` or a generic "send any channel" function.
- Main uses `ipcMain.handle` for request/response. Every handler checks `event.senderFrame` (origin allow-list) and
  validates its arguments before doing anything.
- Do privileged work (files, shell, network with credentials) in main, never in the renderer.
- New channels: use the `electron-ipc-channel` skill.

## Packaging and updates
- Flip fuses at package time with `@electron/fuses`: `RunAsNode` off, `EnableNodeOptionsEnvironmentVariable` off,
  `EnableNodeCliInspectArguments` off, `EnableEmbeddedAsarIntegrityValidation` on, `OnlyLoadAppFromAsar` on,
  `EnableCookieEncryption` on.
- Stay on a supported Electron major. Ask before upgrading a major version; read the breaking changes first.
- Do not sign, notarise, publish or upload builds unless the user asks. Never commit signing certificates or tokens.

## Dependencies
- Ask before adding a dependency. Pin exact versions for anything that runs in main.
- No `@electron/remote`. No native modules unless needed and rebuilt for the Electron version.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `electron-ipc-channel`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Electron desktop app rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/electron-app/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `electron-ipc-channel`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Electron desktop app rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/electron-app/ -->

---
name: electron-ipc-channel
description: Add a typed IPC channel between an Electron renderer and the main process, with a narrow preload API, sender validation and argument checks, then run the security check.
---

# Add an IPC channel

The examples are in `references/`: `main.ts`, `preload.ts` and `renderer-api.d.ts`. Copy the pattern, not the
names.

1. Name the operation after what the user does (`notes:save`), not a generic verb (`send`, `invoke`).
2. Preload: add one function to the object passed to `contextBridge.exposeInMainWorld`. It calls
   `ipcRenderer.invoke` with a fixed channel name and passes only the arguments it needs. Never pass `ipcRenderer`
   itself, an event object, or a channel name chosen by the renderer.
3. Types: add the function to the `window` API declaration so the renderer gets type checking.
4. Main: register `ipcMain.handle(channel, handler)`. In the handler, first call `assertTrustedSender(event)`,
   which checks `event.senderFrame?.origin` against the app's own origin, then validate every argument (type, length,
   allowed values). Throw on bad input; Electron passes the error message to the renderer's promise.
5. Keep the work in main and return plain data (no class instances, functions or Electron objects).
6. Run `node scripts/check_electron_security.mjs src` and fix every finding. Run the type-check.

import { app, BrowserWindow, ipcMain, net, protocol, shell, type IpcMainInvokeEvent } from "electron";
import { join, normalize, sep } from "node:path";
import { pathToFileURL } from "node:url";

const APP_ORIGIN = "app://bundle";
const MAX_NOTE_CHARS = 10_000;
const RENDERER_DIR = join(__dirname, "renderer");
const notes = new Map<string, string>();

// Serve the bundle from app://bundle/ instead of file://, so only files under RENDERER_DIR are reachable.
protocol.registerSchemesAsPrivileged([{ scheme: "app", privileges: { standard: true, secure: true, supportFetchAPI: true } }]);

function serveBundle(request: Request): Promise<Response> | Response {
  const file = normalize(join(RENDERER_DIR, decodeURIComponent(new URL(request.url).pathname)));
  if (!file.startsWith(RENDERER_DIR + sep)) return new Response("not found", { status: 404 });
  return net.fetch(pathToFileURL(file).toString());
}

function assertTrustedSender(event: IpcMainInvokeEvent): void {
  const origin = event.senderFrame?.origin;
  if (origin !== APP_ORIGIN) throw new Error(`untrusted IPC sender: ${origin ?? "unknown"}`);
}

function parseNoteId(value: unknown): string {
  if (typeof value !== "string" || !/^[a-z0-9-]{1,64}$/.test(value)) throw new Error("invalid note id");
  return value;
}

ipcMain.handle("notes:save", (event, id: unknown, text: unknown) => {
  assertTrustedSender(event);
  const noteId = parseNoteId(id);
  if (typeof text !== "string" || text.length > MAX_NOTE_CHARS) throw new Error("invalid note text");
  notes.set(noteId, text);
  return { id: noteId, savedAt: new Date().toISOString() };
});

ipcMain.handle("notes:load", (event, id: unknown) => {
  assertTrustedSender(event);
  return notes.get(parseNoteId(id)) ?? null;
});

function isAllowedExternal(url: string): boolean {
  try {
    return new URL(url).protocol === "https:";
  } catch {
    return false;
  }
}

function createWindow(): BrowserWindow {
  const win = new BrowserWindow({
    width: 1000,
    height: 700,
    webPreferences: {
      preload: join(__dirname, "preload.js"),
      contextIsolation: true,
      sandbox: true,
      nodeIntegration: false,
    },
  });
  win.webContents.setWindowOpenHandler(({ url }) => {
    if (isAllowedExternal(url)) void shell.openExternal(url);
    return { action: "deny" };
  });
  win.webContents.on("will-navigate", (event, url) => {
    if (!url.startsWith(`${APP_ORIGIN}/`)) event.preventDefault();
  });
  void win.loadURL(`${APP_ORIGIN}/index.html`);
  return win;
}

void app.whenReady().then(() => {
  protocol.handle("app", serveBundle);
  createWindow();
  app.on("activate", () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

app.on("window-all-closed", () => {
  if (process.platform !== "darwin") app.quit();
});

import { contextBridge, ipcRenderer } from "electron";

// Small, named functions only. The renderer never sees ipcRenderer or picks a channel name.
const api = {
  saveNote: (id: string, text: string): Promise<{ id: string; savedAt: string }> =>
    ipcRenderer.invoke("notes:save", id, text),
  loadNote: (id: string): Promise<string | null> => ipcRenderer.invoke("notes:load", id),
};

export type NotesApi = typeof api;

contextBridge.exposeInMainWorld("notes", api);

import type { NotesApi } from "./preload";

declare global {
  interface Window {
    notes: NotesApi;
  }
}

export {};

// Run after packaging and before code signing, e.g. from an electron-builder afterPack hook
// or an Electron Forge packageAfterCopy hook. Pass the path to the packaged Electron binary.
import { flipFuses, FuseV1Options, FuseVersion } from "@electron/fuses";

export async function hardenBinary(electronBinary: string, macArm64: boolean): Promise<void> {
  await flipFuses(electronBinary, {
    version: FuseVersion.V1,
    resetAdHocDarwinSignature: macArm64,
    [FuseV1Options.RunAsNode]: false,
    [FuseV1Options.EnableCookieEncryption]: true,
    [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
    [FuseV1Options.EnableNodeCliInspectArguments]: false,
    [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
    [FuseV1Options.OnlyLoadAppFromAsar]: true,
    [FuseV1Options.GrantFileProtocolExtraPrivileges]: false,
  });
}

#!/usr/bin/env node
// Static checks from the Electron security checklist. Pattern-based: it reads files, it runs nothing.
// Usage: node check_electron_security.mjs <dir> [more dirs]
// Exit 1 if anything is found. Checks .js/.mjs/.cjs/.ts/.tsx and .html files, skipping node_modules and build output.
import { readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative } from "node:path";

const SKIP = new Set(["node_modules", "dist", "out", "build", ".git", ".vite", "release"]);
const CODE = /\.(?:[cm]?js|tsx?)$/;

function walk(dir, files = []) {
  for (const name of readdirSync(dir)) {
    if (SKIP.has(name)) continue;
    const p = join(dir, name);
    if (statSync(p).isDirectory()) walk(p, files);
    else if (CODE.test(name) || name.endsWith(".html")) files.push(p);
  }
  return files;
}

const LINE_RULES = [
  [/\bnodeIntegration(?:InWorker|InSubFrames)?\s*:\s*true/, "nodeIntegration enabled: renderer code gets Node.js (checklist 2)"],
  [/\bcontextIsolation\s*:\s*false/, "contextIsolation disabled (checklist 3)"],
  [/\bsandbox\s*:\s*false/, "sandbox disabled (checklist 4)"],
  [/\bwebSecurity\s*:\s*false/, "webSecurity disabled (checklist 6)"],
  [/\ballowRunningInsecureContent\s*:\s*true/, "allowRunningInsecureContent enabled (checklist 8)"],
  [/\bexperimentalFeatures\s*:\s*true/, "experimentalFeatures enabled (checklist 9)"],
  [/\benableBlinkFeatures\s*:/, "enableBlinkFeatures used (checklist 10)"],
  [/\ballowpopups\b/, "allowpopups on a webview (checklist 11)"],
  [/@electron\/remote|\benableRemoteModule\s*:\s*true/, "remote module: renderer reaches main objects directly"],
  [/exposeInMainWorld\([^)]*\bipcRenderer\b\s*\)/, "ipcRenderer exposed to the renderer (checklist 20)"],
  [/exposeInMainWorld\([\s\S]*?\b(?:send|invoke|on)\s*:\s*\(\s*channel\b/, "renderer chooses the IPC channel name (checklist 20)"],
  [/\bipcRenderer\.(?:send|invoke)\(\s*channel\b/, "IPC channel name comes from a variable; use fixed names"],
  [/\bloadURL\(\s*["'`]http:\/\//, "loads content over plain HTTP (checklist 1)"],
  [/\bloadURL\(\s*["'`]file:\/\//, "file:// URL; serve the bundle from a custom protocol (checklist 18)"],
  [/\bRunAsNode\]\s*:\s*true/, "RunAsNode fuse left on (checklist 19)"],
  [/unsafe-eval/, "CSP allows unsafe-eval (checklist 7)"],
];

const findings = [];
const roots = process.argv.slice(2);
if (!roots.length) {
  console.error("usage: node check_electron_security.mjs <dir> [more dirs]");
  process.exit(2);
}
let mainFiles = 0;
let htmlFiles = 0;
for (const root of roots) {
  for (const file of walk(root)) {
    const rel = relative(process.cwd(), file);
    const text = readFileSync(file, "utf8");
    const lines = text.split("\n");
    lines.forEach((line, i) => {
      for (const [re, msg] of LINE_RULES) if (re.test(line)) findings.push(`${rel}:${i + 1}: ${msg}`);
    });
    if (file.endsWith(".html")) {
      htmlFiles++;
      if (!/Content-Security-Policy/i.test(text)) findings.push(`${rel}: no Content-Security-Policy meta tag (checklist 7)`);
      continue;
    }
    if (/new BrowserWindow\(/.test(text)) {
      mainFiles++;
      if (!/setWindowOpenHandler\(/.test(text)) findings.push(`${rel}: BrowserWindow without setWindowOpenHandler (checklist 14)`);
      if (!/["']will-navigate["']/.test(text)) findings.push(`${rel}: no will-navigate handler limiting navigation (checklist 13)`);
    }
    const handlers = [...text.matchAll(/ipcMain\.(?:handle|on)\(\s*["'`]([^"'`]+)["'`]\s*,\s*(?:async\s*)?\(([^)]*)\)\s*=>\s*\{([\s\S]*?)\n\}\);/g)];
    for (const [, channel, , body] of handlers) {
      if (!/senderFrame|assertTrustedSender|validateSender/.test(body)) findings.push(`${rel}: IPC handler "${channel}" does not check event.senderFrame (checklist 17)`);
    }
    for (const m of text.matchAll(/shell\.openExternal\(([^)]*)\)/g)) {
      const before = text.slice(Math.max(0, m.index - 300), m.index);
      if (!/^["'`]https:\/\//.test(m[1].trim()) && !/protocol|isAllowed|allowList|allowlist|startsWith\(\s*["'`]https:/.test(before)) {
        findings.push(`${rel}: shell.openExternal(${m[1].trim()}) without a URL check (checklist 15)`);
      }
    }
  }
}
for (const f of findings) console.log(f);
console.log(findings.length ? `${findings.length} finding(s)` : `ok: no findings (${mainFiles} window file(s), ${htmlFiles} HTML file(s))`);
process.exit(findings.length ? 1 : 0);