# Pathrule Pattern: Electron Desktop Applications (1.0.0) # ::pathrule:package:electron-desktop ### [RULE] Run every renderer with the narrowest privilege set (path: /src/main) 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. - Create BrowserWindow instances through one factory that enables sandboxing and context isolation and does not enable Node integration in the renderer. - Do not weaken web security or certificate verification to make development convenient. Fix origins, certificates, and content policy instead. - Use a strict content security policy appropriate to packaged assets and avoid evaluating strings or loading executable content from writable application data. - 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. See /src/preload for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Expose capability-specific preload methods (path: /src/preload) Exposing `ipcRenderer`, filesystem modules, shell access, or a generic send method through preload turns every renderer injection into an unrestricted privileged command surface. - Expose one named method per allowed capability, with typed arguments and results. Do not expose generic channel strings or the raw IPC object. - Strip Electron event objects before invoking renderer callbacks because they carry privileged sender and frame references. - Validate arguments again in the main process against a runtime schema and authorization context; TypeScript declarations in preload are not a trust boundary. - Return serializable domain values and stable public failures. Do not leak absolute filesystem layout, stack traces, or native object handles into the renderer. See /src/main for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Validate IPC sender, payload, and target resource (path: /src/main) 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. - Check the sender frame's URL and window ownership against the expected packaged application origin before performing a privileged action. - Validate payload shape, size, enum values, and identifiers with a runtime schema before using them in path, command, or native API construction. - Resolve file operations beneath product-owned roots or through user-selected handles; reject traversal and do not accept arbitrary absolute paths from the renderer. - Treat external URL opening as a protocol allowlist decision and construct known destinations from trusted components rather than forwarding a renderer-provided string. See /src/renderer for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] The main process owns durable and privileged state (path: /src/main) 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. - Own windows, tray state, file watchers, protocol registration, update orchestration, and durable database connections in main-process services. - Represent renderer subscriptions with explicit identifiers and remove them when the frame or window closes so main does not retain dead listeners. - 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. - Send renderer updates as serializable events and let the view request a fresh snapshot after reload rather than assuming it observed every transition. See /src/renderer for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Updates are a signed state transition (path: /src/main) 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. - Pin update configuration to the intended product and channel and reject redirects or metadata that escape the trusted distribution boundary. - Require platform signing and verify that the installed update identifies as the same application before replacing the current build. - Do not restart over unsaved work. Surface readiness, release notes, and a user-controlled restart or a clearly documented mandatory policy. - Keep local data migrations forward-compatible with rollback where feasible, or gate irreversible migrations until the new build is confirmed healthy. See /src/main for the rule or workflow that puts this decision into practice. --- ### [SKILL] audit-electron-trust-boundaries (path: /) --- name: audit-electron-trust-boundaries description: Audit an Electron application after adding a window, preload method, native capability, protocol, or updater change. --- # Audit Electron Trust Boundaries 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. - [ ] Enumerate every BrowserWindow and WebView preference, loaded origin, session partition, navigation path, popup handler, and permission decision. - [ ] List the complete contextBridge surface and prove no generic IPC, Node module, event object, or unrestricted path operation reaches the renderer. - [ ] Invoke each IPC handler from the wrong frame with malformed, oversized, stale, unauthorized, and traversal payloads; confirm rejection before side effects. - [ ] Attempt navigation, window creation, download, and external protocol opening with attacker-controlled URLs and mixed encoding. - [ ] 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. ## Exit criteria 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.