Locking the vault means ending a process

Updated 2026-11-22 for 0.3.0, which moved the vault out of the main process into a utility process that every lock ends (D047). The text of 2026-11-09 described 0.1.0.

In an Electron app, clearing state on lock leaves the master password in memory. JavaScript strings are immutable, and nothing in the language can overwrite one. So Local Ledger treats a lock as the end of a process. On every lock, unlock and committed password change, it loads a fresh page in a new renderer process and closes the old one, and the renderer that took the typed password exits. The vault is opened and read in a utility process, the vault host, and every lock ends that process too. Key derivation works the same way: it runs in a worker thread that ends after each derivation. For strings, ending the process is the only reliable way to end their life, and even then the memory becomes unreachable without being erased.

Why clearing state is not enough

Local Ledger is a personal finance desktop app. Its data sits in a database encrypted with SQLite3 Multiple Ciphers in the SQLCipher 4 format, whose key is sealed under a key that Argon2id derives from the master password. The natural way to implement “lock” in a React app is to close the database, clear the store and show the password screen.

That leaves the password where it was typed. It was the value of an input element, then React state, then an argument sent over a port to the vault host. Each of those is a JavaScript string, and strings cannot be wiped. Assigning an empty string to a variable drops one reference and leaves the characters in the heap until garbage collection reclaims them, and V8 may also have copied the string while compacting the heap. Clearing a store changes only what the app can reach.

Binary secrets are easier, because the app can zero a buffer it owns. The data key, the sealing key, the encoded password and the raw key literal live in buffers the app owns and fills with zeros after use, also when an operation fails or is cancelled. While the vault is unlocked, the data key is only inside SQLite, in the vault host. Copies that the key derivation or SQLite make outside these buffers are not wiped by the app; they go when the host ends. The trouble is the text that has to pass through strings on its way into those buffers.

Replacing the page process

D016 hosts the page in a WebContentsView. On every unlock, lock and committed password change, the main process loads the page in a new view and closes the old one, whose renderer process then exits. Two views of the same origin get separate processes. A lock replaces the page even when the vault is already locked, which means a password typed into the unlock screen but never submitted does not survive it either.

Key derivation follows the same rule. D015 runs Argon2id (64 MiB of memory, 3 passes, 4 lanes) in a worker thread that ends after each derivation, releasing its 64 MiB. The worker also keeps the window responsive. On the one machine measured (Electron 45, a 2.1 GHz Xeon with 4 cores), a derivation takes 321 ms; on the main thread it blocked the event loop for 281 ms, and in the worker for 7 ms.

The steps that run at lock time need the vault to lock, so it also locks on its own: after a set idle time (1, 5, 15 or 30 minutes, 5 by default, with no option to turn it off), when the screen locks, when the computer sleeps and when the window closes.

Tests

The end-to-end suite tests the processes. One helper reads the operating system process ID of the page currently shown, another lists the vault host’s, and a third polls until a process no longer exists. The suite records the renderer’s PID before an action that should end the page’s process and waits for it to exit afterwards, across the vault, import, transaction and memory tests. They cover creating a vault, unlocking after a wrong password, locking, closing the window, a lock that arrives while an unlock is still deriving its key, a password typed but not submitted, and a password change. After a lock the suite also waits for the host to exit, and checks that the next page gets a new one.

Heap snapshot tests look at the main process, which does not restart. The one for transactions plants a known control string in the main process, adds a transaction with a random marker in its description, locks, waits for the host that read it to exit, and takes a heap snapshot. A heap snapshot collects garbage first, so it contains only what is still reachable. The test requires the control string to be found, which shows the snapshot can see such strings, and requires the marker to be absent, which shows that the row’s text is not reachable in the process that outlives the lock. A heap snapshot cannot see the contents of Buffers or memory already freed.

Since 0.3.0 one test reads memory itself. On Linux, Windows and macOS it reads the memory of every process of the app three times: unlocked, after a lock once the host and the page have exited and the main process has collected garbage, and 30 s later. It counts copies of a typed description, two imported ones, the 40 seeded descriptions, the master password, the sealing key and the data key. It fails if the main process holds any of them, or if any process does after a lock, apart from two kinds of copy in the main process: text typed into the page, and the page of a PDF export. On macOS it reads the pages the system counts as modified or compressed, so its counts there are a lower bound. Run against 0.2.1, where the main process held the vault, the test found there after a lock, on Linux, 38 copies of the imported text, 36 of the 40 seeded descriptions, the master password, the sealing key and the second half of the data key. D047 records that finding and moves the vault into the host.

Limits

These come from the project’s own security design, which lists what the app does not claim.

  • Strings stay until their process ends. The password is a string in the renderer that took it until that renderer ends, and in the vault host, after crossing its port, until the next lock ends the host. Decrypted rows become strings in the host and stay there until garbage collection, or until the host ends. A call under way at a lock keeps its data there until it settles; a host still running one 30 s after the lock is killed.
  • Freed memory is not overwritten. Memory released by a worker, the vault host or a renderer goes back to the operating system as it is. The app does not scrub it.
  • SQLite’s cache. While unlocked, SQLite keeps up to 16 MB of decrypted pages in the vault host. Closing the database frees them without overwriting, since this build leaves SQLite3 Multiple Ciphers’ secure memory option off.
  • The main process still receives some text. A PDF export hands the page of the month’s statement to the main process, which prints it, and copies of its text stay there after a lock. Copies of a description typed into the page also appear there, though the app’s calls do not carry it; they come from Chromium or from the test driver that types it, and the test does not tell which.
  • Swap and hibernation. The operating system may write any of this memory to disk. The app does not lock pages in memory.
  • Same-user malware is out of scope. While the vault is unlocked, such malware can read process memory or the screen; while it is locked, it can record the password at the next unlock.
  • A failed password change keeps its page. It needs to report the failure, so it clears its fields, but the typed passwords stay in that renderer as strings until the next lock ends it.

After a lock, once the calls under way have settled, no process that opened the vault or showed its rows is still running. The tests check that the old processes exit, that the planted text is unreachable in the main process, and that a read of every process’s memory finds none of the counted text and keys beyond the two kinds of copy in the main process. On macOS that read is a lower bound, and nothing here promises that released memory was erased.

When this does not hold

The approach depends on owning the process model. Electron lets the app create and destroy renderer processes. A web page has no such control, so a browser-based app cannot use this method and has to drop references and wait for the garbage collector.

It also assumes the threat that the project’s model names: someone at the computer after the app has locked itself. Malware already running as the same user is outside that model. If an attacker can read memory while the vault is unlocked, the data is exposed anyway, since it has to be decrypted to be shown.

The approach also has a cost. Each lock reloads the page and discards its state. For a vault whose lock screen already asks for the password again, that cost is small. An app that is expected to resume exactly where the user left off would need to persist that state somewhere, and that state is what the lock was meant to remove.