Decide what you are protecting
An Electron app ships its own JavaScript. Anyone can unpack app.asar, edit a file and repack it. That does not mean licensing is pointless. It means you should be clear about what the check is for.
It is there so that an honest customer sees the right state: licensed, expired, over the device limit, or needing a network. It is not there to stop a determined person who edits your code. Electron’s ASAR integrity feature, which validates the contents of the archive at runtime, raises the effort of casual edits. The documentation lists support on macOS from Electron 16 and on Windows from Electron 30. Turn it on, but do not rely on it alone.
The protection that holds is on the server. Downloads of new builds and update checks can require a valid key, and a signed token cannot be forged without your product’s private key. Those two points matter more than obfuscating the check.
Where the check runs
| Option | Where the key lives | Verdict |
|---|---|---|
| Renderer process | Page memory, possibly localStorage |
Avoid. One cross-site scripting bug, or one third-party script, exposes the key. |
| Main process, renderer asks for a state | Main-process memory and an encrypted file | Use this. The renderer receives licensed, invalid, needs-network or unlicensed. |
| Separate helper process | Helper’s memory | Extra work with little gain for most apps. |
The renderer calls the main process through a preload script and contextBridge. It never receives the key, the token or the instance id. If your interface needs to show the license key, return a masked version such as the first five characters.
Storing the key
Electron’s safeStorage module encrypts a string with a key held by the operating system. As of November 2026 the documentation describes three behaviors worth knowing.
- macOS: the encryption key sits in Keychain. Electron says your app should be code signed for
safeStorageto behave consistently, because without a stable signature macOS may not treat different builds as the same app. - Windows: the key is protected with DPAPI. That protects content from other users on the machine, but not from other apps running as the same user.
- Linux: it depends on the desktop. Electron uses a secret store such as libsecret or KWallet when one is available. When none is,
getSelectedStorageBackend()returnsbasic_text, and what you store is effectively unprotected.
The synchronous methods (isEncryptionAvailable, encryptString, decryptString) are marked deprecated, and the documentation says they will be removed in Electron 46. Clavem’s Electron guide uses the synchronous form because it works on every current version. For new code, use the asynchronous methods:
// main process. Written from the Electron documentation; not run inside Electron.
import { app, safeStorage } from 'electron';
import { readFile, rm, writeFile } from 'node:fs/promises';
import { join } from 'node:path';
const FILE = () => join(app.getPath('userData'), 'license.bin');
export async function saveLicense(license) {
if (!(await safeStorage.isAsyncEncryptionAvailable())) throw new Error('No secure storage here');
await writeFile(FILE(), await safeStorage.encryptStringAsync(JSON.stringify(license)));
}
export async function loadLicense() {
try {
const { result, shouldReEncrypt } = await safeStorage.decryptStringAsync(await readFile(FILE()));
const license = JSON.parse(result);
if (shouldReEncrypt) await saveLicense(license); // the OS key was rotated
return license;
} catch {
return null; // no file, or it cannot be decrypted on this machine
}
}
export const clearLicense = () => rm(FILE(), { force: true });
Handle the failure case on purpose. If isAsyncEncryptionAvailable() is false, you can ask the customer to enter the key at each launch, or keep the key in memory only. Do not quietly write it as plain text.
Verifying the token
Every activate and validate response carries an Ed25519-signed token. Verify it in the main process with node:crypto, which has handled Ed25519 in every Electron version you are likely to ship. Clavem’s documentation says Web Crypto supports Ed25519 from Electron 37, but node:crypto works on older versions too. The function is the same one used in the offline verification page:
import { createPublicKey, verify } from 'node:crypto';
export function verifyToken(token, publicKey) {
const [prefix, body, sig, extra] = String(token).split('.');
if (prefix !== 'sgt1' || !body || !sig || extra !== undefined) return null;
try {
const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKey }, format: 'jwk' });
if (!verify(null, Buffer.from(prefix + '.' + body), key, Buffer.from(sig, 'base64url'))) return null;
return JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
} catch {
return null;
}
}
I ran this function, followed by the claim checks below, in Node 26 against eight test tokens signed with a throwaway key pair: one valid token, one with a changed pid, one past its refresh_by time, one for another product, one with v: 2, one past exp, one for an expired license and one signed by a different key. Only the valid one passed. After the signature, check v, pid, valid, exp and refresh_by after the signature, and compare kh with the first 16 hex characters of the SHA-256 of the key the customer typed, so a token copied from another customer’s machine does not pass as yours.
One more edge case: a customer can set the system clock back to keep an old token looking fresh. If that matters to you, store the highest iat you have seen and treat a clock earlier than it as stale. The check costs one number in the same encrypted file and closes the cheapest way around the 14-day window.
The renderer’s view
Keep the interface between processes this small:
// preload.js
import { contextBridge, ipcRenderer } from 'electron';
contextBridge.exposeInMainWorld('license', {
state: () => ipcRenderer.invoke('license:state'), // 'licensed' | 'invalid' | 'needs-network' | 'unlicensed'
activate: (key) => ipcRenderer.invoke('license:activate', key),
deactivate: () => ipcRenderer.invoke('license:deactivate'),
});
The handlers live in the main process and return states, not secrets. Call the state check at launch and again every few hours while the app stays open, because Clavem’s token carries a refresh_by time 14 days after it was issued and a laptop that sleeps for two weeks needs to notice.
Fingerprints and device limits
node-machine-id returns a hash of the operating system’s machine id, and Clavem’s guide sends it as fingerprint. Activating again with a fingerprint that is already active on the license returns the same seat, so a reinstall or a wiped profile does not use a second seat.
That helps honest customers and has limits. Cloned virtual machines can share an id, and some Linux containers have none. If you cannot get a stable value, omit fingerprint. Activation still works, but a reinstall takes another seat until the customer removes the old one on the device page. See machine fingerprinting pitfalls.
Test licenses and production builds
A Stripe test-mode purchase creates a license with test_mode: true in the license_key object. Decide what your packaged app does with it. A reasonable rule: accept test_mode licenses only when app.isPackaged is false, so your staff can test the whole flow without a test key working in a shipped build.
Updates
Electron’s autoUpdater uses Squirrel on macOS and Windows. On macOS the application must be signed for automatic updates. Squirrel expects a feed in its own format, and Clavem’s releases endpoint returns its own JSON with signed download links, so it is not a drop-in feed. Use the endpoint to learn whether a newer version exists and whether this license may download it, then either open the download link or give autoUpdater a feed your own server builds. The update checks article covers the comparison and entitlement side.
Test matrix before you ship
| Situation | Expected state |
|---|---|
| First launch, no key stored | unlicensed |
| Key entered, network up, device limit free | licensed |
| Key entered, limit reached | Show the error text, state stays unlicensed |
| Launch offline, token younger than 14 days | licensed |
| Launch offline, token older than 14 days | needs-network |
| License refunded or revoked | invalid after the next online check |
| Linux with no secret store | Ask for the key each launch, or keep it in memory |
Doing this with Clavem
Clavem gives you the three License API calls, the signed token and the public key on the product page. The Electron code above fits the calls shown in the guides. Clavem does not ship an SDK package, so the code is yours to copy and own.
Questions
Can someone remove the license check from an Electron app?
Yes. An Electron app is JavaScript on the customer's machine, and the application archive can be edited. ASAR integrity checking makes casual edits harder on current macOS and Windows builds, but no client-side check is tamper-proof. Design for honest customers and keep paid assets such as downloads and updates behind the server.
Should the license check run in the renderer process?
No. Run it in the main process and expose only a result to the renderer through a preload script. A renderer that holds the key can leak it through any cross-site scripting bug.
Does safeStorage work on Linux?
Only as well as the desktop environment allows. Electron uses a secret store such as libsecret or KWallet when one exists. Without one, safeStorage falls back to a basic text backend that offers no real protection.