# 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.