safetynet/docs/electron-best-practices.md

Electron quality and performance review

The current Windows DLP MVP keeps security enforcement as the priority. This review uses the official Electron documentation as the implementation authority: security, performance, context isolation, preloads, IPC, coding style and fuses.

Decisions and implementation

• Keep sandboxing, context isolation, no page Node integration, constrained preload APIs, sender/frame validation and input validation. These need runtime and negative tests; configuration alone does not prove a secure browser.
• Add pinned ESLint tooling and an explicit Node/browser environment contract. Do not hide findings through blanket rule disabling. Dependency advisory results and lint completion are tracked separately from syntax checks.
• Profile before optimizing. scripts/profile-browser-modules.mjs works with Node CPU/heap profiling flags; output belongs in ignored artifacts.
• Defer OpenTelemetry SDK/exporter loading until diagnostics are authorized and enabled. Keep the lightweight diagnostics API available immediately. This shifts initialization cost to first enablement; it does not remove that cost or claim a measured improvement to full browser startup. Seventeen focused diagnostics regression tests pass after this change.
• Load text-normalization code on its first inspection rather than immediately upon requiring its wrapper; subsequent calls reuse the module.
• Keep parsing, OCR and model inference in the isolated worker. Do not move expensive inspection into the renderer or postpone mandatory enforcement.
• Review main-process synchronous filesystem/cryptographic operations using traces before changing behavior. Build CLI spawnSync is separate from the interactive browser event loop.

Bundling and architecture

Electron Forge and the official bundling recommendation are useful options. The existing electron-builder pipeline already verifies Windows runtime contents. Migrating scaffolding is not itself a DLP improvement. Any bundling/code-splitting change must retain sandbox-compatible preloads, dynamic imports, packaged resources, CSP and exact package verification, and must show measured startup or resource improvements before adoption.

The Palette performance article was inspected for additional profiling ideas. Type-safe IPC examples are useful for maintainability; TypeScript types cannot replace runtime validation of untrusted messages. No new IPC framework is needed merely to implement that rule.

Source freshness

The dependency audit reports zero production advisories and eight moderate development/build-toolchain entries, with no high or critical entries at this review point. The underlying sprintf-js precision-format denial-of-service advisory has no patched release reported; suggested electron-builder downgrade is not accepted as a safe remediation. These findings remain explicit tooling risk, not evidence that the deployed browser is vulnerability-free.

The packaged executable's existing fuse wire was inspected separately from JavaScript startup checks. Run-as-Node, Node environment/CLI inspection options and ASAR enforcement need package-level hardening and rebuilt-artifact proof. All six hardened fuse values and the matching embedded ASAR header hash were verified in a rebuilt executable. Actual RUN_AS_NODE and NODE_OPTIONS negative launches passed. The CLI-inspector fixture found a startup error dialog instead of process termination; the source now exits with a sanitized rejection, but the corrected rebuilt package subsequently passed actual negative launches, including eleven certificate/feature override cases and copied-ASAR tampering. The manipulated archive was rejected before application entry; original archive and frozen packaged sources remained unchanged. Evidence: artifacts/package-fuses-proof.json. Actual signing status remains NotSigned.

The supplied Reasonably Secure Electron URL contained a typographic dash. Its correct repository is moloch--/reasonably-secure-electron, archived in June 2024; treat it as historical architecture context rather than current Electron defaults. The supplied dev.to performance page could not be retrieved and was not used as implementation evidence. Other supplied articles were inspected, but version-specific changes must be checked against official documentation and the actual installed runtime.

This review is in progress. Green syntax/tests and one profiling run do not prove that the whole application is clean, fully optimized or independently audited.

Latest reproducible checks

• Full source suite: 749 tests passed, no failures or skips; see the ignored artifacts/mvp-final-startup-suite.log. npm run lint passed again with zero warnings on 2026-10-13.
• A fresh npm audit --omit=dev --json reported zero advisories. Development toolchain findings remain tracked separately in dependency-audit.md.
• In the paired single module-load profiles, diagnostics require time changed from 260.119 ms to 67.001 ms after deferred SDK loading. Recorded heap deltas changed from 6,674,088 to 2,460,832 bytes. Both used CPU/heap profiling; these measurements do not establish full application startup or percentile gains.
• Native Windows DLP fixtures delivered public data and blocked confidential literal and semantic payloads. Restart reused the protected device profile. These are separate from final packaged-artifact acceptance.
• The protected local OpenTelemetry receiver reported zero rejected writes. Trace 33b46998b44c3179cccd2826d5790c00 correlates browser.request, browser.inspect.local, inspector.inspect, semantic load/inference and durable audit stages. The public-file request took 8966 ms in this synthetic run; a contained local text scan took 1611 ms and model load 662 ms. This identifies repeated model initialization as a measurement target, not permission to weaken process isolation or mandatory scanning.
• A native WebRTC initial-about:blank renderer crash remains reproducible under Chromium's connection allowlist. The upstream no-op binder fix is recorded in the upstream regression tests. The separately tested Electron nightly also lacks it. The Windows MVP is not declared stable until an actual fixed runtime passes this negative fixture.
• The full enrolled browser WebTransport receiver fixture now passes through reviewed DIRECT and fetched HTTPS PAC policies: zero managed packets/bytes, paired against 132 baseline bytes, with ordinary HTTPS submissions working. It records source hashes and genuine operational traces. There is still no per-attempt WebTransport security event because this path produces no Electron webRequest callback; transport denial and audit coverage are separate.