kestrove-desktop/README.md

Kestrove for Windows and Linux

The Kestrove desktop app for Windows 10/11 and Linux: your password manager, with a vault encrypted on the computer and synced through your Kestrove server. On a Mac, use the Mac app from kestrove-apple instead: it does everything this app does.

What it does:

• Your vault: logins, one-time codes, tags and "Sign in with Google/Apple", with search and a password generator.
• Connects the Kestrove browser extension (Chrome, Edge, Brave, Firefox) to your vault: filling, saving new logins, and passkeys. You approve each passkey in the app with your master password.
• Adding this computer to your account: scan a QR code with your phone, use your Emergency Kit, or paste a setup code.
• Locks itself after 10 minutes without use (you can change this), when you lock the screen, and when the computer sleeps.
• Closing the window keeps Kestrove running in the tray, so the browser extension keeps working. Quit is in the tray menu.

Install

Download from the releases page:

System	File
Windows (x64)	Kestrove_<version>_x64-setup.exe
Debian, Ubuntu	Kestrove_<version>_amd64.deb, then sudo apt install ./Kestrove_*.deb
Fedora, openSUSE	Kestrove-<version>-1.x86_64.rpm, then sudo dnf install ./Kestrove-*.rpm

Then open Kestrove and add this computer to your account. The easiest way is Use my phone: type your server's address and scan the QR code on screen with the Kestrove app on your phone.

Connect your browser: install the Kestrove extension, open it, and choose Pair with Kestrove. The extension and the app show the same six words; confirm in both. After that, the browser fills from your vault whenever the app is unlocked.

Build it

You need Rust, Node.js 22+, and Tauri's system packages for your OS, with kestrove-core next to this folder.

npm ci
npm run tauri dev            # run it from source
npm run tauri build          # an installer for the system you're on (Windows: .exe; Linux: .deb/.rpm)
(cd src-tauri && cargo clippy --all-targets -- -D warnings && cargo test)

Release builds from a Mac (both write to ../release/desktop/):

# Linux .deb and .rpm, built in a clean Debian 12 container (run from the folder holding the repositories)
docker buildx build --platform linux/amd64 -f kestrove-desktop/scripts/linux.Dockerfile \
  --target out -o type=local,dest=release/desktop .

# Windows installer, cross-compiled. Setting XWIN_ACCEPT_LICENSE=1 accepts Microsoft's
# license for the Windows SDK files it downloads; the script header lists what to install first.
XWIN_ACCEPT_LICENSE=1 scripts/windows.sh

Publish them on Gitea: raise version in package.json, src-tauri/tauri.conf.json and src-tauri/Cargo.toml, tag the commit (git tag v<version> && git push origin v<version>), then:

GITEA_TOKEN=<token with write:repository> TAURI_SIGNING_PRIVATE_KEY_PATH=<updater key> scripts/gitea-release.sh

It creates the release for the tag and uploads the installers, the browser helpers and a SHA256SUMS file.

Offer it as an update (Windows): the script also signs the installer with the updater key, uploads the signature, and writes updater/latest.json. Sign the installer with the code-signing certificate first, because the updater signature covers the final file. Installed copies are offered the update once that file is committed and pushed to main; the script prints the commands. Keep the updater key and its password offline and backed up: the app only accepts updates signed with it, so losing it means existing installs can't update.

How the browser connection works

browser extension ─(native messaging)─▶ kestrove-nmh ─(local connection)─▶ Kestrove app
        └──────────── encrypted end to end with a key you confirm by comparing six words ──────────┘

• kestrove-nmh is a tiny helper that the browser starts. It only passes encrypted messages along; it can't read them.
• The browser has to be told where the helper is: native-messaging/install.sh (Linux) and native-messaging/install.ps1 (Windows) do that, for the extension's id only.
• The extension only ever learns logins for the site you're on, and fills only after you click. Saving a new login, and every passkey use, is confirmed in the app.
• The same code runs inside the Mac app; it lives in kestrove-core (kv-ffi's browser bridge, kv-ipc, kv-nmh).

Updates

On Windows, Kestrove checks for a new version a minute after it starts and once a day. The check is a plain request for updater/latest.json on the Kestrove Gitea: it reveals this computer's IP address and app version, and nothing from your vault. A new version appears as a banner and installs only when you choose Update and restart. The app verifies the download's signature before running it. Turn checks off in Settings → Updates. On Linux, updates come through your package manager.

Where things are kept

The vault and the app's files are in your user's app-data folder (vault.sqlite, pairings.json, settings.json), readable only by you. The key that proves this is your device lives in the TPM on Windows (or is sealed with your Windows login), and in the Secret Service keyring on Linux (or, when there is none, in a private file, which Settings warns about).

For developers

Path	What it is
src/	The window's interface (TypeScript). It only displays things; it never holds keys.
src-tauri/src/	The app (Rust): main.rs commands and prompts, sync.rs sync and onboarding, autolock.rs, device_key.rs.
src-tauri/examples/test-host.rs	A stand-in for the app that approves everything automatically, for the browser extension's tests. Never ship it.
native-messaging/	Registering the browser helper.
scripts/	Release builds (linux.Dockerfile, windows.sh) and gitea-release.sh.

Useful for testing: KESTROVE_DATA_DIR=/tmp/kv-b runs a second, separate instance, and KESTROVE_DEVICE_NAME sets the device name. tests/live_sync.rs (ignored by default) drives three instances against a running server; see its header.

The full design is in kestrove-spec, especially docs/05-autofill.md.