kestrove/kestrove-core
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

README: plain-language guide for users, hosting and building
ci / test (push) Canceled after 0s
Details
ci / wasm (push) Canceled after 0s
Details
ci / deny (push) Canceled after 0s
Details
ci / fuzz (push) Canceled after 0s
Details

Browse Source 
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
sami
2026-10-26 10:21:58 +07:00
co-authored by Claude Opus 5.5
parent 20d465185d
commit 203bd9044d
1 changed files with 65 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+65 -27
View File
@@ -1,44 +1,82 @@
# kestrove-core # Kestrove core
Rust workspace that holds **all** Kestrove crypto and vault logic. Apple, This is the heart of **Kestrove**, the self-hosted password manager. Everything that touches your secrets
Android and desktop apps call it through UniFFI. The server uses only `kv-proto`. lives here, in one Rust codebase that every app shares:
| Crate | Status | Purpose | - 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"…),
| `kv-proto` | ✅ M0 | Wire types (Envelope, KDF params, API bodies). No secrets. | - **sync** with your Kestrove server, and the merging of changes made on two devices at once,
| `kv-crypto` | ✅ M0 | 2SKD (Argon2id + Secret Key), XChaCha20-Poly1305 envelopes, HPKE vault-key sealing, keyset, Ed25519, Secret Key format | - **passkeys** (creating and signing them), **one-time codes**, the **password generator**,
| `kv-model` | ✅ M0 | Items, URL matching (PSL), TOTP (RFC 6238), password generator | - **import** from 1Password and CSV, and encrypted export.
| `kv-ffi` | ✅ M1 | The exported API (`VaultCore` with SQLite storage, local unlock key, sync; `totp_code`, `match_url`, `generate_password`) |
| `kv-store` | ✅ M1 | SQLite replica (ciphertext only), base copies for merges, 10-version history |
| `kv-sync` | ✅ M1 | TLS 1.3 + SPKI pins, OPAQUE login, RFC 9421 signing, pull/push/merge, signed manifest |
Spec: `../kestrove-spec/docs/02-cryptography.md` and `03-sync-protocol.md`. 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.
## Setup 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 ```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # once cargo test --workspace --all-features # every test
cargo test --workspace cargo clippy --workspace --all-targets --all-features
``` ```
## Bindings **Build for the apps:**
```bash ```bash
./scripts/build-apple.sh # → ../kestrove-apple/Packages/KestroveCore (XCFramework + Swift) ./scripts/build-apple.sh # → ../kestrove-apple/Packages/KestroveCore (needs Xcode)
./scripts/build-android.sh # → ../kestrove-android/core-ffi (jniLibs + Kotlin); needs cargo-ndk 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)
``` ```
The desktop (Tauri) app depends on `kv-ffi` directly as a Rust crate. Run these again after changing the core, so the apps pick up the change.
## Test vectors and the live-server test **Test against a real server** (start a fresh local `kestrove-server` first; the test file explains how):
```bash ```bash
cargo run -p kv-crypto --example gen-vectors # writes crates/kv-crypto/tests/vectors and ../kestrove-spec/vectors cargo test -p kv-ffi --test live_server -- --ignored
cargo test -p kv-ffi --test live_server -- --ignored # against a fresh local kestrove-server; see the test's docs
``` ```
## Rules ## What's inside
* No `unsafe` outside generated FFI glue.
* Secrets live in `Zeroizing<_>`. Never log, `Debug`-print or `format!` a secret. | Crate | What it does |
* Any change to formats needs a spec change first and new vectors in `kestrove-spec/vectors`. |---|---|
* `cargo deny check` must pass. There are no GPL dependencies (App Store). | `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.