Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Security Model

Safe Storage, Fuses and Hardening Your Build

Encrypt secrets with Electron's safeStorage, flip Electron Fuses to remove risky features, understand ASAR integrity, and finish with a release hardening routine.

You have locked the windows, controlled navigation and validated every IPC call. Two questions remain: where do the secrets sit on disk, and what can someone do to the application files themselves? Electron answers the first with safeStorage and the second with Fuses and ASAR integrity.

Be realistic about what these tools achieve. They defend against casual access, other users on the machine and malware that copies files. They do not make secrets safe from a determined attacker running as the same user on an unlocked session. Security is about raising the cost and removing the easy wins.

safeStorage

safeStorage encrypts a string with a key held by the operating system: the macOS Keychain, Windows DPAPI, or a Linux secret service (libsecret, kwallet). The encrypted bytes are what you write to disk; only your app, running as that user, can decrypt them.

JavaScript
import { app, safeStorage } from 'electron';
import { readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';

const tokenFile = () => join(app.getPath('userData'), 'token.bin');

export async function saveToken(token) {
  if (!safeStorage.isEncryptionAvailable()) throw new Error('no secure storage on this system');
  await writeFile(tokenFile(), safeStorage.encryptString(token));
}

export async function loadToken() {
  try {
    return safeStorage.decryptString(await readFile(tokenFile()));
  } catch {
    return null;
  }
}

Points to remember:

  • Call it only after app.whenReady(); on Linux, availability depends on the desktop. Check isEncryptionAvailable(), and on Linux also getSelectedStorageBackend(): basic_text means no real keyring and the "encryption" is weak.
  • The result is a Buffer, so write it as binary, not as a string.
  • Never fall back to saving the plain token when encryption is unavailable. Ask the user to sign in again each session instead.
  • Do not put the decrypted value in the renderer; see Validating IPC and Handling Secrets.

Packages such as keytar and its successors do the same through the system keychain, and are suited to many separate credentials.

An envelope you can run

Electron's key lives in the OS, which we cannot reach here. The idea around it is portable: encrypt before writing, authenticate what you read, and fail closed. This stand-in uses Node's crypto with AES-256-GCM and a key that pretends to be the OS-held key.

Node.js Encrypting a token before it touches disk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

GCM adds an authentication tag, so even a single flipped bit makes decryption fail instead of returning garbage. safeStorage gives you the same guarantee without you managing the key.

Electron Fuses

Electron ships as a prebuilt binary with many features you may never use, and some of them are dangerous in an attacker's hands. For example, ELECTRON_RUN_AS_NODE=1 turns your signed app into a general Node interpreter. A fuse is a switch flipped in the binary itself at package time, so it cannot be changed by environment variables or command-line flags after you ship.

The important fuses:

Fuse Set to Why
RunAsNode off Stops the app acting as node through the environment variable
EnableNodeCliInspectArguments off Blocks --inspect debugging of production builds
EnableNodeOptionsEnvironmentVariable off Ignores NODE_OPTIONS injection
EnableCookieEncryption on Encrypts cookies on disk
EnableEmbeddedAsarIntegrityValidation on Verifies app.asar has not been modified
OnlyLoadAppFromAsar on Refuses to load code from loose folders
GrantFileProtocolExtraPrivileges off, if you serve over a custom protocol Removes extra rights of file:// pages

With @electron/fuses you flip them in a build step:

JavaScript
import { flipFuses, FuseVersion, FuseV1Options } from '@electron/fuses';

await flipFuses(pathToElectronBinary, {
  version: FuseVersion.V1,
  [FuseV1Options.RunAsNode]: false,
  [FuseV1Options.EnableNodeCliInspectArguments]: false,
  [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
  [FuseV1Options.EnableCookieEncryption]: true,
  [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
  [FuseV1Options.OnlyLoadAppFromAsar]: true,
});

If you use Electron Forge, the Fuses plugin runs this for you. Flip fuses before code signing, since changing the binary invalidates the signature (see Installers and Code Signing).

ASAR and its integrity

Your JavaScript is packed into app.asar, an archive Electron reads like a folder. ASAR is not encryption: anyone can unpack it with npx @electron/asar extract. What matters is integrity: with the embedded integrity fuse on, Electron records a hash of the archive header at build time and refuses to start if the archive was edited. That blocks the trivial "unpack, patch a line, repack" attack on the installed app.

Do not put secrets in your source or ASAR. API keys in a bundle are public keys. If a service needs a secret, keep it on your server and let the app talk to your server.

A hash check in miniature

This stand-in shows the principle behind integrity validation: record a digest at build time, recompute at startup, and refuse to run on mismatch.

Node.js Detecting a modified bundle

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A release hardening routine

Before every release go through this short list:

  1. Security flags checked (from the checklist), CSP present, permission handlers installed.
  2. Secrets only in safeStorage; no keys in source, in the ASAR or in logs.
  3. Fuses flipped, ASAR integrity on, RunAsNode off.
  4. Electron updated to a supported release: only the latest few major versions get security fixes.
  5. Dependencies audited (npm audit), unused ones removed.
  6. Build signed, notarized on macOS, and distributed over https.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does safeStorage.encryptString return?

    It returns a Buffer of encrypted bytes. Store them as a binary file, and decrypt with safeStorage.decryptString.
  2. 2. What should you do if safeStorage.isEncryptionAvailable() is false?

    Falling back to plain storage defeats the purpose. Keeping the secret only in memory for the session is the safe choice.
  3. 3. What is the effect of turning the RunAsNode fuse off?

    Your main process still runs Node code. The fuse only removes the ability to abuse the signed binary as a general-purpose node executable.
  4. 4. Is app.asar encrypted?

    ASAR is just an archive format. Integrity checking detects tampering but does not hide the contents, so never embed secrets.

Summary

  • safeStorage encrypts small secrets with an OS-held key; check availability and never fall back to plain text.
  • Fuses permanently disable risky binary features such as RunAsNode; flip them before signing.
  • ASAR integrity detects tampering with the packaged code, but ASAR is not encryption.
  • Never ship secrets in the app; keep them on a server.
  • Use a repeatable hardening routine for every release.

Next: Packaging with Electron Forge