storage(), Beta

storage() creates a secure token storage adapter for the Electron main process. The adapter persists tokens with electron-store⁠ and encrypts them at rest with Electron's safeStorage⁠ API, which is backed by the OS keystore: Keychain on macOS, DPAPI on Windows, and libsecret or KWallet on Linux. Pass the result to createClerkBridge().

electron-store is an optional peer dependency of @clerk/electron (peer range ^8.2.0). Install it when you use storage():

npm install electron-store@8

pnpm add electron-store@8

yarn add electron-store@8

bun add electron-store@8

Usage

import { createClerkBridge } from '@clerk/electron'
import { storage } from '@clerk/electron/storage'

createClerkBridge({ storage: storage({ name: 'my-app-tokens' }) })

Options

Behavior

• The adapter writes values as enc:<base64 ciphertext> when encrypted, or raw:<value> when unencryptedFallback applies. Entries in any other format are deleted on read. Entries that fail to decrypt are kept and read as null.
• On Electron 42 and later, Electron uses the asynchronous safeStorage API when it reports itself available; otherwise it uses the synchronous API. Availability is decided by Electron and the OS at runtime.
• enc: means the value went through Electron's safeStorage, which isn't the same as OS-keystore protection on every platform. On Linux without a keyring, Electron can select its basic_text backend, which encrypts with a hard-coded key and still reports encryption as available; the adapter doesn't inspect the selected backend. If that matters for your app, check safeStorage.getSelectedStorageBackend() on Linux and decide whether to persist tokens at all. The unencryptedFallback rules apply only when Electron reports encryption as unavailable.
• When the OS rotates its key, the adapter silently re-encrypts the value.
• When persistence is unavailable or a write fails, the adapter keeps the token in memory for the life of the process, so the user stays signed in until the app exits. On macOS this is what happens in an unsigned or ad-hoc-signed packaged app: safeStorage can't obtain a Keychain entry, and the console shows Keychain lookup failed. Sign the app (see the deployment guide); npm start is unaffected.
• Out-of-order IPC writes can't overwrite a newer token with an older one.

The adapter logs one warning per instance, for the first of these conditions it hits:

Custom storage

To store tokens somewhere else, pass any object matching the TokenStorage type instead. See Custom storage.