83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# Kestrove core
|
|
|
|
This is the heart of **Kestrove**, the self-hosted password manager. Everything that touches your secrets
|
|
lives here, in one Rust codebase that every app shares:
|
|
|
|
- the **encryption** (your master password and Secret Key turn into the keys that lock your vault),
|
|
- the **vault** itself (logins, passkeys, one-time codes, notes, cards, tags, "Sign in with Google"…),
|
|
- **sync** with your Kestrove server, and the merging of changes made on two devices at once,
|
|
- **passkeys** (creating and signing them), **one-time codes**, the **password generator**,
|
|
- **import** from 1Password and CSV, and encrypted export.
|
|
|
|
Because all apps use this same code, a vault works the same on iPhone, Mac, Android, Windows, Linux and in
|
|
the browser, and the security-critical parts are written and reviewed once.
|
|
|
|
You only need this repository to **build the apps** or to work on Kestrove itself. To run a server, see
|
|
[`kestrove-server`](https://gitea.samialabri.com/kestrove/kestrove-server).
|
|
|
|
## How the apps use it
|
|
|
|
| App | How it gets the core |
|
|
|---|---|
|
|
| iPhone, iPad, Mac (`kestrove-apple`) | `scripts/build-apple.sh` builds a Swift package |
|
|
| Android (`kestrove-android`) | `scripts/build-android.sh` builds the native libraries and Kotlin bindings |
|
|
| Windows and Linux (`kestrove-desktop`) | Uses the Rust code directly |
|
|
| Web vault (`kestrove-web`) | `crates/kv-wasm/build.sh` builds a WebAssembly package (`kestrove-web` keeps a copy) |
|
|
| Server (`kestrove-server`) | Uses only the shared message formats (`kv-proto`); it never handles secrets |
|
|
|
|
Keep the repositories **side by side in one folder** (`kestrove-core`, `kestrove-apple`, …): the apps find
|
|
the core by that relative path.
|
|
|
|
## Build and test
|
|
|
|
You need Rust (install it once from [rustup.rs](https://rustup.rs)):
|
|
|
|
```bash
|
|
cargo test --workspace --all-features # every test
|
|
cargo clippy --workspace --all-targets --all-features
|
|
```
|
|
|
|
**Build for the apps:**
|
|
|
|
```bash
|
|
./scripts/build-apple.sh # → ../kestrove-apple/Packages/KestroveCore (needs Xcode)
|
|
ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/27.3.13750724 ./scripts/build-android.sh
|
|
# → ../kestrove-android/core-ffi (needs the Android NDK and cargo-ndk)
|
|
(cd ../kestrove-web && scripts/vendor-core.sh)
|
|
# → builds kv-wasm and copies it into the web vault (needs wasm-pack)
|
|
```
|
|
|
|
Run these again after changing the core, so the apps pick up the change.
|
|
|
|
**Test against a real server** (start a fresh local `kestrove-server` first; the test file explains how):
|
|
|
|
```bash
|
|
cargo test -p kv-ffi --test live_server -- --ignored
|
|
```
|
|
|
|
## What's inside
|
|
|
|
| Crate | What it does |
|
|
|---|---|
|
|
| `kv-crypto` | Keys and encryption: turning the master password and Secret Key into keys (Argon2id), sealing every item (XChaCha20-Poly1305), sealing vault keys for devices (HPKE), signatures (Ed25519). |
|
|
| `kv-model` | Vault items and what's in them, website matching (which login belongs to which site), one-time codes (TOTP), passkey signing (WebAuthn), the password generator. |
|
|
| `kv-store` | The encrypted copy of the vault kept on each device (SQLite). It stores only ciphertext. |
|
|
| `kv-sync` | Talking to the server: login without sending the password (OPAQUE), signed requests, pulling and pushing changes, merging edits from two devices, and a signed summary that catches a server hiding or rolling back data. |
|
|
| `kv-proto` | The message formats shared with the server. No secrets. |
|
|
| `kv-ffi` | The one API every app calls (`VaultCore`): create an account, unlock, read and save items, passkeys, sync, add devices. Also the browser bridge that the Mac and desktop apps use to answer the browser extension. |
|
|
| `kv-wasm` | The same API for the web vault, as WebAssembly in a Web Worker. |
|
|
| `kv-import` | Import from 1Password (`.1pux`) and CSV, and passphrase-encrypted export (`.kvex`). |
|
|
| `kv-ipc`, `kv-nmh` | The small helper (`kestrove-nmh`) that browsers start to reach the Kestrove app, and its local connection to the app. |
|
|
|
|
The design behind all this, with the reasons, is in
|
|
[`kestrove-spec`](https://gitea.samialabri.com/kestrove/kestrove-spec): start with `docs/02-cryptography.md`
|
|
and `docs/03-sync-protocol.md`.
|
|
|
|
## Rules for changes
|
|
|
|
- No `unsafe` code outside the generated bindings.
|
|
- Secrets are kept in `Zeroizing<…>` so they're wiped from memory, and are never logged or printed.
|
|
- Changing a stored or transmitted format? Change the spec first, then add test vectors to
|
|
`kestrove-spec/vectors` (`cargo run -p kv-crypto --example gen-vectors` writes them).
|
|
- No GPL dependencies (the apps go to the App Store); `cargo deny check` must pass.
|