Electron Desktop Applications

Pathrule3 Rules • 2 Memories • 1 Skill

Electron combines a privileged Node main process with web-rendered content, so a renderer bug becomes a desktop compromise when preload exposure, IPC routing, navigation, permissions, or update trust are broader than the feature requires. This pattern constrains renderer privileges and IPC validation, records window and local-data ownership, separates main-process services from UI state, and adds an adversarial desktop release audit. It differs from ordinary web security because the protected capabilities include filesystem, operating-system integration, native dialogs, protocol handlers, and signed application updates.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

audit-electron-trust-boundaries

src/

main/

Run every renderer with the narrowest privilege set

Validate IPC sender, payload, and target resource

The main process owns durable and privileged state

Updates are a signed state transition

preload/

Expose capability-specific preload methods

Rules

Run every renderer with the narrowest privilege set/src/mainhighstrictKeep sandboxing and context isolation enabled, disable renderer Node access, and create windows from one reviewed factory.

1	A renderer processes HTML, styles, user content, and sometimes remote data. It must be treated as an untrusted presentation process even when every asset is packaged locally.
2
3	- Create BrowserWindow instances through one factory that enables sandboxing and context isolation and does not enable Node integration in the renderer.
4	- Do not weaken web security or certificate verification to make development convenient. Fix origins, certificates, and content policy instead.
5	- Use a strict content security policy appropriate to packaged assets and avoid evaluating strings or loading executable content from writable application data.
6	- Partition sessions deliberately and clear sensitive session data on sign-out where the product contract requires it; do not let incidental window creation choose storage isolation.
7
8	See /src/preload for the adjacent decision or procedure that completes this constraint.

Expose capability-specific preload methods/src/preloadhighstrictPublish a small typed API through the context bridge and keep Electron event objects, channels, and Node primitives private.

1	Exposing `ipcRenderer`, filesystem modules, shell access, or a generic send method through preload turns every renderer injection into an unrestricted privileged command surface.
2
3	- Expose one named method per allowed capability, with typed arguments and results. Do not expose generic channel strings or the raw IPC object.
4	- Strip Electron event objects before invoking renderer callbacks because they carry privileged sender and frame references.
5	- Validate arguments again in the main process against a runtime schema and authorization context; TypeScript declarations in preload are not a trust boundary.
6	- Return serializable domain values and stable public failures. Do not leak absolute filesystem layout, stack traces, or native object handles into the renderer.
7
8	See /src/main for the adjacent decision or procedure that completes this constraint.

Validate IPC sender, payload, and target resource/src/mainhighstrictAuthorize each privileged handler against the calling frame and selected resource before touching files, shell, clipboard, or operating-system APIs.

1	IPC originates from a renderer that may be compromised. A valid channel name alone does not prove the caller is an expected application frame or that the requested path and operation are allowed.
2
3	- Check the sender frame's URL and window ownership against the expected packaged application origin before performing a privileged action.
4	- Validate payload shape, size, enum values, and identifiers with a runtime schema before using them in path, command, or native API construction.
5	- Resolve file operations beneath product-owned roots or through user-selected handles; reject traversal and do not accept arbitrary absolute paths from the renderer.
6	- Treat external URL opening as a protocol allowlist decision and construct known destinations from trusted components rather than forwarding a renderer-provided string.
7
8	See /src/renderer for the adjacent decision or procedure that completes this constraint.

Memories

The main process owns durable and privileged state/src/mainKeep operating-system resources, update state, windows, and durable local services in main while renderers hold disposable view state.

1	Renderer processes can reload or crash independently. Durable work tied to a renderer disappears at the wrong lifetime, while privileged objects mirrored into UI state become hard to revoke.
2
3	- Own windows, tray state, file watchers, protocol registration, update orchestration, and durable database connections in main-process services.
4	- Represent renderer subscriptions with explicit identifiers and remove them when the frame or window closes so main does not retain dead listeners.
5	- Keep local database migrations and encryption setup before renderer access, with a failure screen that does not open the main application against a partial schema.
6	- Send renderer updates as serializable events and let the view request a fresh snapshot after reload rather than assuming it observed every transition.
7
8	See /src/renderer for the rule or workflow that puts this decision into practice.

Updates are a signed state transition/src/mainDownload only from the configured trusted channel, verify package identity, and stage restart and rollback behavior as product flows.

1	Desktop update failures persist on user machines and can prevent the application from starting. Automatic update code must treat origin, signing, compatibility, restart timing, and rollback as one transition.
2
3	- Pin update configuration to the intended product and channel and reject redirects or metadata that escape the trusted distribution boundary.
4	- Require platform signing and verify that the installed update identifies as the same application before replacing the current build.
5	- Do not restart over unsaved work. Surface readiness, release notes, and a user-controlled restart or a clearly documented mandatory policy.
6	- Keep local data migrations forward-compatible with rollback where feasible, or gate irreversible migrations until the new build is confirmed healthy.
7
8	See /src/main for the rule or workflow that puts this decision into practice.

Skills

audit-electron-trust-boundaries/rootAttack renderer, preload, IPC, navigation, permission, file, protocol, and update boundaries before a desktop release.

1	---
2	name: audit-electron-trust-boundaries
3	description: Audit an Electron application after adding a window, preload method, native capability, protocol, or updater change.
4	---
5
6	# Audit Electron Trust Boundaries
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	- [ ] Enumerate every BrowserWindow and WebView preference, loaded origin, session partition, navigation path, popup handler, and permission decision.
11	- [ ] List the complete contextBridge surface and prove no generic IPC, Node module, event object, or unrestricted path operation reaches the renderer.
12	- [ ] Invoke each IPC handler from the wrong frame with malformed, oversized, stale, unauthorized, and traversal payloads; confirm rejection before side effects.
13	- [ ] Attempt navigation, window creation, download, and external protocol opening with attacker-controlled URLs and mixed encoding.
14	- [ ] Install a valid update, a tampered package, a wrong-channel package, and an update around unsaved work and local-data migration; record recovery for every outcome.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often enable Node integration in renderers, expose raw ipcRenderer through preload, trust renderer-provided paths or channels, or open arbitrary URLs with operating-system privileges.

Built for Teams shipping Electron applications with local files, native integrations, or automatic updates.

Keeps your assistant from:

Giving remote or compromised renderer code direct Node access
Accepting arbitrary IPC channels and unvalidated payloads
Opening attacker-controlled navigation or external protocols
Applying an update without a verifiable origin and rollback plan

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25