samiandClaude Opus 5.5
d70dcc04b6
The Microsoft Store doesn't update EXE installs, so the app updates itself with Tauri's updater. It reads updater/latest.json from the Kestrove Gitea a minute after startup and once a day. A new version shows as a banner and in Settings > Updates, and installs only on "Update and restart". The vault locks before the installer takes over. The installer must be signed with the Kestrove updater key, with the signature bound to its version (requireSignedVersion), so a compromised download server can hold updates back but can't ship one or replay an old installer. Signing is a release step, after Authenticode: gitea-release.sh signs, uploads the .sig, and writes latest.json last. Plain builds need no key. Checks reveal only the IP address and app version, and can be turned off in Settings. endpoints is a list, so a mirror can be added. Linux packages update through their package manager. Co-Authored-By: Claude Opus 5.5 <[email protected]>
124 lines
6.4 KiB
Markdown
124 lines
6.4 KiB
Markdown
# 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`.
|