[garrettmflynn]

Summary

Breaking changes:

• Packaged Electron pages now load from app://local instead of file://. Set electron: { origin: 'file' } to keep the old behaviour.
• Desktop and PWA tooling (electron, electron-builder, vite-plugin-pwa) are optional peer dependencies. Apps that build for desktop install them (npm i -D electron electron-builder); create-commoners projects already do. A missing package stops the build with the exact install command.
• Electron peer range is now ^41.10.6 (security fixes).
• Default appId. When a config sets no appId, the default is now com. followed by the app name in lowercase letters and digits (My App becomes com.myapp), with no .app suffix. A name of app, or an empty name, gives com.commonersapp. The old default was com.<name>.app. Apps that never set appId get a new identifier (macOS bundle id, Windows app id, Tauri identifier, mobile application id), so their data and settings paths can move. Set appId explicitly to keep the previous one. See docs/guide/config.md.
  • Windows installer: electron-builder derives the NSIS installer GUID from appId. An upgrade over an install built with the old default is therefore expected to install side by side, with a second uninstall entry, rather than replace it (inferred from the GUID computation; the installer was not run).
  • Electron data: userData follows the name in package.json, not appId, so it does not move (observed on Windows).
  • Tauri data: the app data and WebView data directories follow the identifier, so they are expected to move with it (inferred from where Tauri places them; not run on an upgraded install).

Hardens the desktop runtime and brings the Tauri backend to working parity with Electron, plus cross-window streaming, an overlay window, and one security policy for every target.

Desktop substrate (Electron)

• postMessage with transfer lists on the plugin context, including MessagePort handoff through the preload
• Tolerant renderer contexts for windows with a custom preload; worker-src for module workers; wasm-pack packages externalized in config bundles; single-instance opt-out; BLE device permissions; haptics plugin

Tauri

• Sidecars spawn by bare name, survive a failed spawn, receive HOST, and are killed on exit and on SIGTERM/Ctrl-C
• The Tauri CLI is found from any working directory
• User Rust plugins via tauri.plugin (path + permissions), and ctx.tapPort to forward stream frames into Rust
• Default CSP at parity with Electron (workers, WASM, IPC)

Cross-window streaming

• ctx.sendPort / ctx.onPort hand a MessagePort to any window over BroadcastChannel (namespaced per app, late-join handshake, bounded pre-attach buffer)
• desktop.backgroundThrottling: false keeps hidden windows at full rate
• READY now resolves only after async plugin loads finish

Overlay

• desktop.overlay: transparent, click-through, always-on-top window covering the display, on Electron and Tauri, including over other apps' fullscreen Spaces on macOS

Security

• One CSP builder for Electron, Tauri and web/PWA (object-src 'none', base-uri, form-action, inline scripts only by hash)
• Web/PWA builds emit a meta CSP and a _headers file; preview serves the same headers

Build record (evidence for every production build)

• .commoners/records/<target>/ gets three files, written outside the deployable output:
  • a CycloneDX 1.5 SBOM of what actually shipped: bundled npm packages, the Electron runtime or the Tauri crates, service dependencies, and built services with hashes;
  • a manifest of target, features, security settings, file and installer hashes, and source commit;
  • a SARIF 2.1.0 scan report.
• commoners record-tests <junit.xml> ties JUnit results to the manifest of the build they exercised.
• SOURCE_DATE_EPOCH gives reproducible records.

Features and compile-out

• features per target become build-time defines, so disabled code is removed rather than hidden.
• A canary gate fails the build if a disabled feature's code ships, or an enabled feature's code is missing.

Electron hardening

• app://local origin by default: a real origin, CSP as a response header, cross-origin isolation available, and no fetch() of arbitrary local files.
• Links leave the app only for https:, http: and mailto: (electron.security.externalProtocols).
• Node-entry fuses (RunAsNode, NODE_OPTIONS, --inspect) are off on every packaged build (electron.security.fuses).
• Electron's 20-item security checklist is mapped in docs/guide/security.md. SECURITY.md uses private vulnerability reporting.

Repo health

• tsc --noEmit is clean: 77 errors fixed.
• Lint no longer scans build output.
• Formatting-only commit, listed in .git-blame-ignore-revs.
• CI fast tests fixed on every OS: the cold-build test now uses the built CLI, and Linux runs Electron under xvfb.

Docs

• Positioning: "From prototype to product, for everyone."
• Tauri is documented as shipped.
• New Security guide.
• Config docs for features, buildRecord, electron.origin.

Dependencies and supply chain

• Core's production install went from 794 to 242 packages. Unused dependencies were removed, and target tooling is now an optional peer.
• DEPENDENCIES.md justifies every runtime dependency, enforced by a test. Other tests enforce a footprint budget, and a web build must work with desktop tooling unresolvable.
• pnpm audit --audit-level=high passes (from 116 high / 9 critical). Accepted advisories are documented in SECURITY.md, and a test keeps them matched to pnpm.auditConfig.
• Reproducible builds: deterministic output names, so two builds give byte-identical records.
• The SBOM covers the NTIA minimum elements (suppliers, author, dependency graph).
• Fixed: the CLI swallowed uncaught exceptions (silent exit 0), and core's ESM build used bare require().

Reliability

• A stale build lock from a killed CLI is reclaimed and its processes are stopped (process registry)
• start() closes its services when its close is destructured
• Test suites exercise the workspace packages, not published versions; several tests that asserted nothing now assert

Test plan

• Fast unit suite, CSP, build, start, and desktop build/start/launch suites pass on macOS arm64
• Tauri demo builds and launches with sidecars; SIGTERM leaves no processes
• Overlay verified on both backends from the window server (level, bounds, on-screen), including over a fullscreen app
• Port channels measured across windows (Electron p95 ~1 ms, Tauri < 1 ms); Rust tap 60 Hz with 0 gaps
• Web build checked in headless Chromium: 0 CSP violations, injected inline script blocked
• CI fast tests and service tests pass on ubuntu, macos and windows (Node 20/22)
• Build record: SBOMs validate against the CycloneDX 1.5 schema; SARIF validates against 2.1.0; feature gate mutation-tested end to end
• Fuses read back Disabled from packaged builds (stock Electron: Enabled); ELECTRON_RUN_AS_NODE no longer runs the app as Node
• Desktop suites and packaged checks on Windows hardware
• Tauri E2E on Windows/Linux (tauri-driver is unsupported on macOS)

[garrettmflynn]

Design note: Electron checklist #5, a permission request handler

Not implemented in this PR yet. This is the proposed design, written up so it can be reviewed before it is built.

Today

• No setPermissionRequestHandler is set, so Electron's default applies: every permission request is granted, for any page in the window.
• The serial plugin calls session.setPermissionCheckHandler(() => true) and setDevicePermissionHandler(() => true) on the default session. That allows every permission check, for every origin, for the whole app, whenever the plugin is loaded.
• The Bluetooth plugin needs no permission grant (Web Bluetooth goes through select-bluetooth-device), but it auto-confirms pairing.

Proposal

1. Deny by default, in core. main.ts installs both a request handler and a check handler on every session it creates windows in. A permission is granted only when both of these hold:
   • the requesting frame is an app page, using the same origin policy as IPC sender validation (app://local, the dev server, app files under file://, electron.security.ipcOrigins);
   • the permission is on the app's allow-list.
2. Plugins declare what they need. A plugin adds desktop.permissions: string[] to its definition, using Electron's permission names. For example, a camera plugin declares ['media'] (optionally narrowed to mediaTypes: ['video']); the serial plugin declares ['serial']; the Bluetooth plugin declares ['bluetooth'] if Electron starts asking for it. Core builds the allow-list from the plugins that are loaded, the same way the IPC channel allowlist is built from declared plugins and services.
3. Apps can extend it explicitly. Add electron.security.permissions: string[] for permissions the app uses directly, outside any plugin.
4. Plugins stop installing global handlers. The serial plugin's allow-everything check and device handlers are replaced by its declaration, plus a device handler limited to serial devices requested by app pages.
5. Visibility. A denied request emits a security:permission:denied hook event with the permission and the origin, so an app can see what it is missing during development.
6. Docs. docs/guide/security.md item 5 becomes "Yes: requests are denied unless a loaded plugin or electron.security.permissions declares them, and only for app pages".

Tests

• Unit (policy): an undeclared permission is denied; a declared one is granted for an app origin and denied for a foreign origin and for a foreign subframe; electron.security.permissions adds to the list. Positive control: the tests fail with the handler removed.
• Electron, launched (desktop-zlaunch), with Chromium's fake media device (--use-fake-device-for-media-stream, --use-fake-ui-for-media-stream):
  • a test plugin that declares media gets a live getUserMedia({ video: true }) track;
  • the same call without the declaration is denied (NotAllowedError);
  • an undeclared permission (for example notifications or geolocation) is denied.
• Bluetooth and serial: the existing plugin tests keep passing with the declarations in place. Real devices cannot be tested in CI, so this checks the declaration and the selection flow, not a radio.

Compatibility. This is a breaking change for apps whose pages use a permission (camera, microphone, notifications, geolocation) without a plugin that declares it. They add electron.security.permissions. It will be listed under Breaking changes when it lands.

Open questions

• Whether to deny by default or warn by default for one alpha release, then deny.
• Whether media declarations should narrow to video or audio (Electron passes mediaTypes in the request details).