Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Update Rust core README (#1404)

Leendert de Borstfa127360395a
diff --git a/core/rust/README.md b/core/rust/README.md
index ef83bf0c6..12288a384 100644
--- a/core/rust/README.md
+++ b/core/rust/README.md
@@ -1,210 +1,371 @@
# AliasVault Rust Core
-Cross-platform core library for AliasVault, providing shared business logic for **native platforms**:
-- **Mobile Apps** (iOS via Swift bindings, Android via Kotlin bindings)
-- **Server** (.NET via P/Invoke)
-- **Desktop Apps** (future)
+Cross-platform core library providing shared business logic for all AliasVault clients:
-> **Note:** Browser extensions use the TypeScript [VaultMergeService](../../apps/browser-extension/src/utils/VaultMergeService.ts) with sql.js (pre-compiled SQLite WASM). This is more efficient than re-compiling SQLite via Rust to WASM.
+- **Browser Extensions** (Chrome, Firefox, Edge, Safari via WASM)
+- **Mobile Apps** (iOS via Swift bindings, Android via Kotlin bindings)
+- **Server** (.NET via P/Invoke - currently only scaffolding, not actively used)
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────┐
-│ Rust Core Library │
-│ ┌─────────────────────────────────────────────────────────────────────┐│
-│ │ src/lib.rs - Main library entry point ││
-│ │ src/merge.rs - Vault merge service (LWW strategy) ││
-│ │ src/types.rs - Common types and table configurations ││
-│ │ src/error.rs - Error types ││
-│ └─────────────────────────────────────────────────────────────────────┘│
+│ Rust Core Library │
+│ │
+│ src/ │
+│ ├── lib.rs Entry point, module exports │
+│ ├── error.rs VaultError type │
+│ ├── vault_merge/ LWW merge algorithm │
+│ ├── vault_pruner/ Trash retention cleanup │
+│ └── credential_matcher/ Autofill filtering │
+│ │
+│ Platform Interfaces: │
+│ ├── wasm.rs WASM bindings (#[wasm_bindgen]) │
+│ ├── uniffi_api.rs UniFFI bindings (#[uniffi::export]) │
+│ └── ffi.rs C FFI for .NET (extern "C") │
└─────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
-│ UniFFI (FFI) │ │ UniFFI (FFI) │ │ C FFI (.NET) │
-│ Swift bindings │ │ Kotlin bindings │ │ P/Invoke │
+│ WASM Module │ │ UniFFI (FFI) │ │ C FFI (.NET) │
+│ wasm-bindgen │ │ Swift + Kotlin │ │ P/Invoke │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
-│ iOS Mobile │ │ Android Mobile │ │ Server │
-│ App │ │ App │ │ (.NET) │
+│ Browser │ │ iOS & Android │ │ Server │
+│ Extensions │ │ Mobile Apps │ │ (.NET) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
-## Prerequisites
+## Core Modules
-### Required
-- **Rust** (1.70+): Install via [rustup](https://rustup.rs/)
- ```bash
- curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- ```
+### vault_merge
+Last-Write-Wins (LWW) merge algorithm for syncing local and server vaults.
-### For iOS builds (macOS only)
-- **Xcode** with command line tools
+### vault_pruner
+Permanently deletes items in trash older than retention period (default: 30 days).
-### For Android builds
-- **Android NDK**: Set `ANDROID_NDK_HOME` environment variable
-- **cargo-ndk**: For Android cross-compilation (installed automatically)
- ```bash
- cargo install cargo-ndk
- ```
+### credential_matcher
+Priority-based credential filtering for autofill with anti-phishing protection.
## Building
-### Build all targets
```bash
-./build.sh
+./build.sh --browser # WASM for browser extension
+./build.sh --ios # iOS device + simulator with Swift bindings
+./build.sh --android # Android ABIs with Kotlin bindings
+./build.sh --dotnet # Native library for .NET
+./build.sh --mobile # iOS + Android
+./build.sh --all # All targets
```
-### Build specific targets
+## Testing
+
```bash
-./build.sh --ios # iOS only (macOS required)
-./build.sh --android # Android only (NDK required)
-./build.sh --csharp # C#/.NET only
+cargo test # All tests
+cargo test vault_merge # Specific module
+cargo test --features uniffi # With UniFFI enabled
```
-### Manual builds (for development)
-```bash
-# iOS (device)
-cargo build --release --target aarch64-apple-ios --features uniffi
+---
-# Android (arm64)
-cargo ndk --target aarch64-linux-android --platform 21 -- build --release --features uniffi
+# Developer Guide
-# Native (current platform)
-cargo build --release
-```
+This section documents the interface structure and how to add new functionality.
+
+## Interface Overview
+
+The Rust core exposes functions through three interface files, each targeting different platforms:
+
+| Interface | File | Platforms | Attribute |
+|-----------|------|-----------|-----------|
+| WASM | `src/wasm.rs` | Browser extensions | `#[wasm_bindgen]` |
+| UniFFI | `src/uniffi_api.rs` | iOS, Android | `#[uniffi::export]` |
+| C FFI | `src/ffi.rs` | .NET Server | `#[no_mangle] extern "C"` |
-## Output Structure
+All interfaces follow a JSON-in/JSON-out pattern for simplicity. Each platform handles its own database I/O and passes data as JSON to Rust.
-After building, artifacts are placed in `dist/` and distributed to consumer apps:
+## Current Exported Functions
+| Function | WASM | UniFFI | C FFI | Description |
+|----------|------|--------|-------|-------------|
+| `getSyncableTableNames` | ✓ | ✓ | ✓ | Returns list of syncable table names |
+| `mergeVaults` / `mergeVaultsJson` | ✓ | ✓ (JSON only) | ✓ | LWW merge of local + server vaults |
+| `pruneVault` / `pruneVaultJson` | ✓ | ✓ (JSON only) | ✓ | Remove expired trash items |
+| `filterCredentials` / `filterCredentialsJson` | ✓ | ✓ (JSON only) | ✓ | Credential matching for autofill |
+| `extractDomain` | ✓ | ✓ | - | Extract domain from URL |
+| `extractRootDomain` | ✓ | ✓ | - | Extract root domain (handles .co.uk etc) |
+
+## Adding a New Function
+
+When adding a new module or function to the Rust core, you need to update multiple files. Follow this checklist:
+
+### 1. Implement the Core Logic
+
+Create or update a module in `src/`:
+
+```rust
+// src/my_module/mod.rs
+
+use serde::{Deserialize, Serialize};
+use crate::error::VaultResult;
+
+#[derive(Serialize, Deserialize)]
+pub struct MyInput {
+ pub data: String,
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct MyOutput {
+ pub result: String,
+}
+
+/// Core function with typed input/output.
+pub fn my_function(input: MyInput) -> VaultResult<MyOutput> {
+ // Implementation
+ Ok(MyOutput { result: input.data })
+}
+
+/// JSON wrapper for cross-platform convenience.
+pub fn my_function_json(input_json: &str) -> VaultResult<String> {
+ let input: MyInput = serde_json::from_str(input_json)?;
+ let output = my_function(input)?;
+ Ok(serde_json::to_string(&output)?)
+}
```
-dist/
-├── ios/ # iOS libraries
-│ ├── device/
-│ │ └── libaliasvault_core.a
-│ ├── simulator/
-│ │ └── libaliasvault_core.a (universal)
-│ └── aliasvault_core.swift
-├── android/ # Android libraries
-│ ├── arm64-v8a/
-│ │ └── libaliasvault_core.so
-│ ├── armeabi-v7a/
-│ │ └── libaliasvault_core.so
-│ ├── x86_64/
-│ │ └── libaliasvault_core.so
-│ ├── x86/
-│ │ └── libaliasvault_core.so
-│ └── aliasvault_core.kt
-└── csharp/ # C# libraries
- ├── osx-arm64/
- │ └── libaliasvault_core.dylib
- ├── osx-x64/
- │ └── libaliasvault_core.dylib
- ├── linux-x64/
- │ └── libaliasvault_core.so
- └── VaultMergeService.cs
+
+### 2. Export from lib.rs
+
+```rust
+// src/lib.rs
+
+pub mod my_module;
+pub use my_module::{my_function, MyInput, MyOutput};
```
-## Usage
+### 3. Add WASM Bindings (src/wasm.rs)
-### Swift (iOS)
+```rust
+use crate::my_module::{my_function, MyInput, MyOutput};
-```swift
-import AliasVaultCore
+/// Typed API - accepts/returns JsValue.
+#[wasm_bindgen(js_name = myFunction)]
+pub fn my_function_js(input: JsValue) -> Result<JsValue, JsValue> {
+ let input: MyInput = serde_wasm_bindgen::from_value(input)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse input: {}", e)))?;
-let mergeService = VaultMergeService()
+ let output: MyOutput = my_function(input)
+ .map_err(|e| JsValue::from_str(&format!("Failed: {}", e)))?;
-do {
- let result = try mergeService.merge(
- localVaultBase64: localVault,
- serverVaultBase64: serverVault
- )
+ serde_wasm_bindgen::to_value(&output)
+ .map_err(|e| JsValue::from_str(&format!("Failed to serialize: {}", e)))
+}
- print("Merged \(result.stats.tablesProcessed) tables")
- print("New vault: \(result.mergedVaultBase64.prefix(50))...")
-} catch {
- print("Merge failed: \(error)")
+/// JSON API - accepts/returns strings.
+#[wasm_bindgen(js_name = myFunctionJson)]
+pub fn my_function_json_js(input_json: &str) -> Result<String, JsValue> {
+ crate::my_module::my_function_json(input_json)
+ .map_err(|e| JsValue::from_str(&format!("Failed: {}", e)))
}
```
-### Kotlin (Android)
+### 4. Add UniFFI Bindings (src/uniffi_api.rs)
-```kotlin
-import net.aliasvault.core.VaultMergeService
+```rust
+use crate::error::VaultError;
-val mergeService = VaultMergeService()
-
-try {
- val result = mergeService.merge(
- localVaultBase64 = localVault,
- serverVaultBase64 = serverVault
- )
+/// JSON API only - UniFFI handles type conversion automatically.
+#[uniffi::export]
+pub fn my_function_json(input_json: String) -> Result<String, VaultError> {
+ crate::my_module::my_function_json(&input_json)
+}
+```
- println("Merged ${result.stats.tablesProcessed} tables")
- println("Conflicts: ${result.stats.conflicts}")
-} catch (e: Exception) {
- println("Merge failed: ${e.message}")
+### 5. Add C FFI Bindings (src/ffi.rs) - If Needed for .NET
+
+```rust
+/// C-compatible function for .NET P/Invoke.
+///
+/// # Safety
+/// - `input_json` must be a valid null-terminated C string
+/// - Returned pointer must be freed with `free_string()`
+#[no_mangle]
+pub unsafe extern "C" fn my_function_ffi(input_json: *const c_char) -> *mut c_char {
+ if input_json.is_null() {
+ return ptr::null_mut();
+ }
+
+ let c_str = match CStr::from_ptr(input_json).to_str() {
+ Ok(s) => s,
+ Err(_) => return ptr::null_mut(),
+ };
+
+ let input: MyInput = match serde_json::from_str(c_str) {
+ Ok(i) => i,
+ Err(e) => return create_error_response(&format!("Parse failed: {}", e)),
+ };
+
+ let output = match my_function(input) {
+ Ok(o) => o,
+ Err(e) => return create_error_response(&format!("Failed: {}", e)),
+ };
+
+ match serde_json::to_string(&output) {
+ Ok(json) => string_to_c_char(json),
+ Err(e) => create_error_response(&format!("Serialize failed: {}", e)),
+ }
}
```
-### C# (.NET)
+### 6. Update Cargo.toml Features (If Needed)
-```csharp
-using AliasVault.Shared.RustCore;
+If your module requires additional dependencies, ensure they're properly feature-gated:
-var result = VaultMergeService.Merge(localVaultBase64, serverVaultBase64);
+```toml
+[features]
+wasm = ["dep:wasm-bindgen", "dep:serde-wasm-bindgen"]
+uniffi = ["dep:uniffi"]
+ffi = []
-Console.WriteLine($"Merged {result.Stats.TablesProcessed} tables");
-Console.WriteLine($"Conflicts: {result.Stats.Conflicts}");
-Console.WriteLine($"Records from server: {result.Stats.RecordsFromServer}");
+[dependencies]
+my-new-dep = { version = "1.0", optional = true }
```
-## Development
+### 7. Add Tests
-### Running tests
-```bash
-cargo test
+```rust
+// In src/my_module/mod.rs or src/my_module/tests.rs
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_my_function() {
+ let input = MyInput { data: "test".to_string() };
+ let output = my_function(input).unwrap();
+ assert_eq!(output.result, "test");
+ }
+
+ #[test]
+ fn test_my_function_json() {
+ let input = r#"{"data": "test"}"#;
+ let output = my_function_json(input).unwrap();
+ assert!(output.contains("test"));
+ }
+}
```
-### Checking code
+### 8. Build and Distribute
+
```bash
-cargo clippy
-cargo fmt --check
+# Build for all targets you support
+./build.sh --browser --ios --android
+
+# Or just the ones you need during development
+./build.sh --browser
+```
+
+## Platform Consumption
+
+After building, the outputs are distributed to:
+
+| Platform | Output Location | Files |
+|----------|----------------|-------|
+| Browser Extension | `apps/browser-extension/src/utils/dist/core/rust/` | `aliasvault_core.js`, `.wasm`, `.d.ts` |
+| Blazor WASM | `apps/server/AliasVault.Client/wwwroot/wasm/` | `aliasvault_core.js`, `.wasm` |
+| iOS | `apps/mobile-app/ios/VaultStoreKit/RustCore/` | `.a`, `.h`, `.swift` |
+| Android | `apps/mobile-app/android/app/src/main/jniLibs/` | `.so` per ABI + `.kt` |
+
+### Browser Extension Usage
+
+```typescript
+import init, { myFunction, myFunctionJson } from '@/utils/dist/core/rust/aliasvault_core.js';
+
+// Initialize once
+await init(wasmBytes);
+
+// Typed API
+const result = myFunction({ data: "test" });
+
+// JSON API
+const jsonResult = myFunctionJson('{"data": "test"}');
+```
+
+### iOS Usage (Swift)
+
+```swift
+// Generated UniFFI bindings in aliasvault_core.swift
+let result = try myFunctionJson(inputJson: jsonString)
```
-### Adding new functionality
+### Android Usage (Kotlin)
+
+```kotlin
+// Generated UniFFI bindings
+val result = uniffi.aliasvault_core.myFunctionJson(jsonString)
+```
-1. Add Rust implementation in `src/`
-2. Update `src/aliasvault_core.udl` for UniFFI bindings
-3. Run `./build.sh` to generate all bindings
+## Design Decisions
-## Binary Size Considerations
+### JSON-First Communication
-The compiled native libraries include SQLite bundled statically. Approximate sizes:
+All interfaces use JSON strings for input/output. This simplifies:
+- Cross-language type marshalling
+- Debugging (human-readable)
+- Consistency across platforms
-| Target | Approximate Size |
-|--------|-----------------|
-| iOS (arm64 static) | ~20MB |
-| Android (arm64 shared) | ~2-3MB |
-| macOS (.dylib) | ~16KB (dynamic) |
+For WASM, we also provide typed APIs using `serde-wasm-bindgen` for better TypeScript integration.
-> **Note:** Binaries are NOT committed to the repository. They are built:
-> 1. Locally via `./build.sh` when needed
-> 2. In CI pipelines for deployment
-> 3. In Docker builds for containerized deployments
+### Feature Flags
-## Why Rust for Native, TypeScript for Browser?
+| Feature | Purpose | Used By |
+|---------|---------|---------|
+| `uniffi` | UniFFI runtime support | iOS/Android builds |
+| `uniffi-cli` | UniFFI binding generator | Build script only |
+| `wasm` | WASM + JS interop | Browser extension |
+| `ffi` | C-compatible exports | .NET server |
-- **Browser Extensions**: Already use sql.js (SQLite compiled to WASM). Re-compiling SQLite via Rust to WASM adds complexity without benefit since sql.js already handles this well.
-- **Native Platforms**: Rust compiles to native code with excellent SQLite support. UniFFI generates idiomatic Swift/Kotlin bindings automatically.
-- **Consistency**: Both implementations follow the same LWW merge algorithm, ensuring identical behavior across all platforms.
+Use `uniffi` (not `uniffi-cli`) for library builds to avoid pulling in heavy bindgen dependencies.
-## License
+### Error Handling
+
+Use `VaultError` from `src/error.rs` for all errors:
+
+```rust
+use crate::error::{VaultError, VaultResult};
+
+pub fn my_function() -> VaultResult<String> {
+ // serde errors auto-convert via From impl
+ let data: MyType = serde_json::from_str(json)?;
+
+ // Manual error creation
+ if data.invalid {
+ return Err(VaultError::General("Invalid data".to_string()));
+ }
+
+ Ok("success".to_string())
+}
+```
-MIT License - see the main AliasVault repository for details.
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `src/lib.rs` | Entry point, exports all modules |
+| `src/error.rs` | `VaultError` and `VaultResult` types |
+| `src/vault_merge/mod.rs` | LWW merge implementation |
+| `src/vault_merge/types.rs` | Table configurations, composite keys |
+| `src/vault_pruner/mod.rs` | Trash cleanup implementation |
+| `src/credential_matcher/mod.rs` | Autofill filtering algorithm |
+| `src/credential_matcher/domain.rs` | URL/domain extraction utilities |
+| `src/credential_matcher/stop_words.rs` | Text filtering for service name matching |
+| `src/wasm.rs` | WASM bindings (browser) |
+| `src/uniffi_api.rs` | UniFFI bindings (iOS/Android) |
+| `src/ffi.rs` | C FFI bindings (.NET) |
+| `uniffi-bindgen.rs` | UniFFI CLI binary entry point |
+| `build.sh` | Multi-platform build script |
+| `Cargo.toml` | Dependencies and feature flags |
\ No newline at end of file