110 lines
5.3 KiB
Markdown
110 lines
5.3 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> scripts/gitea-release.sh
|
|
```
|
|
|
|
It creates the release for the tag and uploads the installers, the browser helpers and a `SHA256SUMS` file.
|
|
|
|
## 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`).
|
|
|
|
## 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`.
|