# 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](https://gitea.samialabri.com/kestrove/kestrove-desktop/releases):

| 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](https://rustup.rs), Node.js 22+, and
[Tauri's system packages](https://tauri.app/start/prerequisites/) for your OS, with `kestrove-core` next to
this folder.

```bash
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/`):

```bash
# 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:

```bash
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`](https://gitea.samialabri.com/kestrove/kestrove-spec), especially
`docs/05-autofill.md`.