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](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> scripts/gitea-release.sh
```

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

**Put it on the website and offer it as an update (Windows):**

```bash
TAURI_SIGNING_PRIVATE_KEY_PATH=<updater key> scripts/publish-update.sh
```

This signs the installer with the updater key, copies it to `downloads/` in `kestrove-website` next to this repo,
and writes `updates/latest.json` there. Sign the installer with the code-signing certificate first, because the
updater signature covers the final file. Installed copies are offered the update once the website is deployed.
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 `updates/latest.json` on the Kestrove website: 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`.