Skip to content

Build from Source

Jump to bottom
RakinSV edited this page Jun 20, 2026 · 1 revision

Build from Source

Complete instructions for building LSPV from source on Windows, Linux, and macOS.

Prerequisites

All platforms

Tool Version Install
Rust 1.96+ rustup.rs
Node.js 20+ nodejs.org
npm 10+ Bundled with Node.js

Windows

  • Microsoft C++ Build Tools (MSVC 2019+) — Download
    • Select: "Desktop development with C++"
    • Alternative: Full Visual Studio Community (includes MSVC)
  • WebView2 Runtime — pre-installed on Windows 11, available from Microsoft for Windows 10

Linux

# Ubuntu / Debian
sudo apt install build-essential \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  libsecret-1-dev \
  pkg-config

# Arch Linux
sudo pacman -S base-devel webkit2gtk-4.1 gtk3 libayatana-appindicator libsecret

# Fedora
sudo dnf install @development-tools webkit2gtk4.1-devel \
  gtk3-devel libappindicator-gtk3-devel libsecret-devel

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Clone the Repository

git clone https://github.com/RakinSV/local-security-pass-vault.git
cd local-security-pass-vault

Build the Core Library

# Build all Rust crates (core-vault, desktop backend)
cargo build

# Run all tests including crypto test vectors
cargo test

# Security audit — check for known CVEs in dependencies
cargo audit

Build the Desktop App

cd desktop

# Install JavaScript dependencies
npm install

# Development mode (hot reload, debug build)
npm run tauri dev

# Production release build
npm run tauri build

Release artifacts (after tauri build)

Windows:

desktop/src-tauri/target/release/bundle/nsis/Local Security Pass Vault_*_x64-setup.exe
desktop/src-tauri/target/release/bundle/msi/Local Security Pass Vault_*_x64_en-US.msi

Linux:

desktop/src-tauri/target/release/bundle/appimage/local-security-pass-vault_*.AppImage
desktop/src-tauri/target/release/bundle/deb/local-security-pass-vault_*_amd64.deb

macOS:

desktop/src-tauri/target/release/bundle/dmg/Local Security Pass Vault_*.dmg
desktop/src-tauri/target/release/bundle/macos/Local Security Pass Vault.app

Build the Browser Extension

cd extension

# Install dependencies
npm install

# Development build (watch mode)
npm run dev

# Production build
npm run build

# SRI integrity check on built files
node scripts/sri-check.js

Built extension is in extension/dist/. Load it in Chrome via chrome://extensions → Developer mode → Load unpacked.

Run the Test Suite

# All Rust tests
cargo test

# Specific crate
cargo test -p core-vault

# Run with output (verbose)
cargo test -- --nocapture

# Specific test
cargo test crypto::tests::argon2id_rfc9106_test_vector

# Extension unit tests
cd extension && npm test

Static Analysis

# Rust lints (zero warnings enforced in CI)
cargo clippy -- -D warnings

# Check formatting
cargo fmt --check

# CVE scan
cargo audit

Environment Variables

Variable Default Description
LSPV_LOG info Log level: error, warn, info, debug, trace
LSPV_DATA_DIR Platform default Override vault storage directory

Platform defaults:

  • Windows: %APPDATA%\lspv\
  • Linux: ~/.local/share/lspv/
  • macOS: ~/Library/Application Support/lspv/

Development Workflow

Backend-only changes (Rust)

# Fast iteration — no frontend rebuild
cargo test -p core-vault

# Test Tauri commands
cd desktop && cargo test -p lspv-desktop

Frontend-only changes (React)

cd desktop && npm run tauri dev
# App reloads automatically on .tsx/.css changes

Adding a new Tauri command

  1. Add the command function in desktop/src-tauri/src/commands/
  2. Register it in desktop/src-tauri/src/lib.rs in the .invoke_handler(tauri::generate_handler![...])
  3. Call it from React via invoke('command_name', { args })

CI Pipeline

CI runs on every push and pull request:

# .github/workflows/security.yml
jobs:
  - cargo audit       # CVE scan
  - cargo clippy      # static analysis
  - cargo test        # all tests on Ubuntu + Windows
  - sri-check         # extension SRI integrity
  - fuzz (weekly)     # cargo fuzz on vault_open + item_deserialize

Crypto Rules (read before touching core-vault)

See .claude/rules/crypto.md for mandatory rules:

  • Never use rand::thread_rng() — use randombytes_buf() from libsodium
  • Fresh 192-bit nonce on every record save — never reuse
  • sodium_memzero() on every key after use — never memset()
  • sodium_memcmp() for MAC comparison — never ==
  • Only libsodium for crypto — no openssl, ring, or separate argon2 crate

Project Structure

local-security-pass-vault/
├── core-vault/               # Rust crypto core
│   └── src/
│       ├── crypto/           # Argon2id KDF, XChaCha20, HMAC search index
│       ├── backup/           # BIP-39 + BLAKE3 backup (.vbk format)
│       ├── models.rs         # Item types, vault schema
│       └── db.rs             # SQLCipher integration
├── desktop/                  # Tauri 2 desktop app
│   ├── src/                  # React + Tailwind UI
│   │   ├── pages/
│   │   │   ├── VaultList.tsx
│   │   │   ├── ItemForm.tsx
│   │   │   ├── ItemDetail.tsx
│   │   │   └── Settings/
│   │   │       ├── General.tsx
│   │   │       ├── Security.tsx
│   │   │       ├── Backup.tsx
│   │   │       ├── Browser.tsx
│   │   │       ├── Import.tsx
│   │   │       ├── Data.tsx    # Folders, Trash, Health, CSV export
│   │   │       └── About.tsx
│   └── src-tauri/            # Rust backend
│       ├── src/
│       │   ├── commands/     # Tauri IPC commands
│       │   ├── browser/      # Native messaging host
│       │   └── tray.rs       # System tray
│       └── tauri.conf.json
├── extension/                # Browser extension (MV3)
│   ├── src/
│   │   ├── background/       # Native messaging bridge + Ed25519 verify
│   │   ├── content/          # Auto-fill content script
│   │   └── popup/            # React popup
│   └── scripts/
│       └── sri-check.js      # SRI integrity verification
├── docs/
│   ├── adr/                  # Architecture Decision Records
│   ├── screenshots/          # App screenshots
│   ├── wiki/                 # GitHub Wiki pages
│   ├── index.html            # GitHub Pages landing
│   └── threat-model.md
└── .claude/rules/            # Developer crypto & security rules
    ├── crypto.md
    ├── security.md
    ├── vault-schema.md
    ├── browser-extension.md
    ├── testing.md
    └── backup.md

Clone this wiki locally