VAULTEX

Zero-Knowledge End-to-End Encrypted Messaging

Overview

VAULTEX is a zero-knowledge, end-to-end encrypted messaging application built for users and organizations that refuse to compromise on privacy. Unlike conventional secure messengers that still collect metadata, require phone numbers, or store social graphs server-side, VAULTEX is designed so that the server never has access to plaintext messages, private keys, contact lists, IP addresses, or any user metadata whatsoever.

The cryptographic foundation implements the Signal protocol (X3DH key agreement and Double Ratchet message encryption) using audited, production-grade libsodium primitives. Every message benefits from mandatory forward secrecy and post-compromise security. Sealed sender construction ensures that even the server cannot determine who is communicating with whom.

VAULTEX is fully open source and auditable. There are no proprietary black boxes, no phone number or email requirements, and no trust placed in any third party. Identity is purely cryptographic: users generate and control all keys locally on their own device.

Key Features

• End-to-End Encryption -- X3DH key agreement combined with Double Ratchet message encryption, providing forward secrecy and post-compromise security on every message.
• Zero-Knowledge Server -- The server stores only encrypted blobs, public keys, and delivery tokens. It never sees plaintext, private keys, contact lists, or user metadata.
• Sealed Sender -- Cryptographic construction that hides sender identity from the server, preventing social graph analysis even by a compromised relay.
• Sovereign Identity -- No phone number or email required. Users are identified solely by their cryptographic keys, eliminating real-world identity linkage.
• Forward Secrecy -- Mandatory per-message key ratcheting ensures that compromise of current keys cannot decrypt past messages.
• Post-Compromise Security -- Automatic key healing restores security after a temporary device compromise.
• Cross-Platform -- Desktop application via Tauri (Linux, Windows, macOS). Android and iOS apps via Rust FFI with React Native shared UI.
• P2P Off-Grid Messaging -- Four transport backends (local network, Wi-Fi Direct, Bluetooth, Tor) with automatic mesh relay for offline and censorship-resistant communication.
• Voice and Video Calls -- End-to-end encrypted voice and video calls with WebRTC, SRTP key derivation from the Double Ratchet, screen sharing, and group video.
• Honest Connectivity -- A real server handshake (/api/v1/ping capability probe) and a "Test Connection" diagnostic that reports the true state — reachable, not a VAULTEX server, or your account isn't registered here — instead of optimistically claiming "connected".
• Opt-In Discovery -- Off by default. Users may choose to be findable by display name on a server; others can browse and add them after confirming the safety-number fingerprint. End-to-end encryption is never weakened, and users who don't opt in remain invisible.
• Open Source and Auditable -- Fully transparent codebase with no proprietary dependencies in the cryptographic path.

Architecture

VAULTEX uses a Rust + React/TypeScript dual stack with Tauri as the desktop shell.

Rust Workspace

Applications

Infrastructure

Docker Compose stack with PostgreSQL 16, Redis 7, Nginx for TLS termination and reverse proxying, and the Rust server.

Security Model

What the Server Knows

The server is designed under a zero-trust model. It processes and relays encrypted blobs but has no ability to:

• Read message content
• Identify message senders (sealed sender)
• Access private keys
• Reconstruct contact lists or social graphs
• Correlate IP addresses to user identities

What the Server Stores

Only the minimum required for delivery: public identity keys, signed pre-keys, one-time pre-keys, and encrypted message payloads queued for offline delivery.

Cryptographic Primitives

Key Management

• All key generation occurs on the user's device and never leaves it.
• Private keys are protected by the zeroize crate to ensure memory is wiped after use.
• Pre-keys are rotated regularly and uploaded to the server as public-key bundles.
• Local storage keys are derived via Argon2id from a user-chosen PIN.

Getting Started

There are three ways to run VAULTEX, depending on what you're doing:

Quick Start: run a server (Docker)

The fastest way to get a working VAULTEX backend on any computer that has Docker:

git clone https://gitlab.com/secureapps/vaultex.git
cd vaultex/infrastructure
cp .env.example .env                  # safe dev defaults; override as you like
docker compose up -d                  # postgres + redis + server + nginx
curl http://localhost:8080/api/v1/health

That's it. The server is now reachable at http://localhost:8080 (and http://<this-host's-LAN-IP>:8080 from other PCs on the same network — useful for testing). Stop with docker compose down. To wipe state, docker compose down -v.

For TLS, a real domain, and automated deploys, follow infrastructure/DEPLOYMENT.md.

Install the desktop client

The desktop app is not distributed via Docker — it's a native Tauri GUI. Download the platform-specific installer from GitLab → Releases:

On first launch, point the app at your server URL (Settings → Server Connection). Use http://<server-host>:8080 for a local LAN server, or https://<your-domain> for a TLS-fronted production server. Click Test Connection to verify the URL actually reaches a VAULTEX server before you commit to it — it distinguishes "unreachable", "not a VAULTEX server", and "reachable but your account isn't registered here" rather than just claiming success.

Build from source (developers)

Prerequisites:

• Rust (stable): rustup.rs with clippy + rustfmt
• Node.js ≥ 20 LTS
• Docker + Compose v2 (for running the server stack while developing)
• Tauri prerequisites (platform-specific):
  • Linux: sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libayatana-appindicator3-dev librsvg2-dev
  • Windows: WebView2 (pre-installed on Windows 10/11)
  • See Tauri v2 prerequisites for full details

git clone git@gitlab.com:secureapps/vaultex.git
cd vaultex
rustup component add clippy rustfmt

# Start infrastructure services (PostgreSQL, Redis, Nginx, server)
cd infrastructure && docker compose up -d && cd ..

# Build + test the Rust workspace
cargo build --workspace
cargo test --workspace

# Set up the desktop frontend
cd apps/desktop && npm install && npm test

# Launch the desktop app in development mode (HMR enabled)
cargo tauri dev

# Build a native installer for this platform
cargo tauri build      # output → apps/desktop/src-tauri/target/release/bundle/

Run the Server (recommended — persistent Postgres + Redis)

For any real test, especially cross-machine, use the persistent stack. It survives restarts:

# Linux / macOS / WSL
scripts/dev-server-up.sh

# Windows PowerShell
.\scripts\dev-server-up.ps1

The script brings up Postgres + Redis via Docker, waits for them to be healthy, then runs the server binary natively. The companion scripts/dev-server-down.sh (and .ps1) shuts everything down — pass --wipe if you also want to clear the data volumes.

Demo Mode (no Docker — for unit tests only)

Demo mode runs the server with in-memory storage. Every restart wipes every account, every contact, every message. This is fine for unit tests, CI, or a quick local kick-the-tires, but it is not appropriate for cross-machine testing — clients will silently fall back to local-only mode if the server has forgotten their account.

VAULTEX_DEMO=1 cargo run -p vaultex-server

The server prints a loud warning banner at startup when running in demo mode.

Useful Commands

# Lint and format checks
cargo clippy --workspace --all-targets
cargo fmt --all -- --check
cd apps/desktop && npx eslint src/ --ext .ts,.tsx

# Frontend type checking
cd apps/desktop && npx tsc --noEmit

# Security audit
cargo audit

For complete development environment setup, pre-commit hooks, and tooling details, see CONTRIBUTING.md.

Project Status

VAULTEX is under active development. Phases 1 through 5 are complete; Phase 6 (Video Chat) is in progress.

What Is Implemented

Cryptography (crates/vaultex-crypto/):

• Ed25519 identity keys, X25519 key agreement, X3DH session establishment, Double Ratchet
• XChaCha20-Poly1305 symmetric encryption, sealed sender, safety numbers
• Group messaging, per-file media encryption, message padding, self-destructing messages
• 128+ unit tests and 6 end-to-end integration tests

Server (crates/vaultex-server/):

• Axum REST API with account registration, prekey management, message delivery, media upload
• WebSocket relay with Ed25519 auth, call signaling, typing indicators, read receipts
• Ed25519 challenge-response auth middleware, rate limiting
• Unauthenticated GET /api/v1/ping capability probe (service, version, min client version, capabilities) for client pre-flight
• Opt-in user discovery (default off): authenticated set/read-back of discoverability and a rate-limited, self-excluded listing endpoint
• PostgreSQL 16 + Redis 7 backends, or in-memory demo mode (VAULTEX_DEMO=1)

Desktop App (apps/desktop/):

• Full chat UI with contacts, conversations, message search, reactions, editing
• PIN and duress PIN protection (Argon2id), app lock with configurable timeout
• State persistence via SQLCipher, configurable server URL, delivery receipts
• Voice call UI with incoming call overlay, mute/hangup controls, call history
• Test Connection diagnostic and honest server-status reporting (Settings → Server Connection)
• Reset Local Data (Settings → Danger Zone): typed-confirmation wipe that securely scrubs the local database and key material, then restarts on a fresh-account screen
• Actionable add-contact feedback: when session establishment fails (e.g. the server was reset), the UI explains why and what to do instead of silently going local-only
• Privacy → opt-in discovery toggle and a Browse Server dialog to find and add discoverable peers after confirming their fingerprint

Transport (crates/vaultex-transport/):

• Four backends: local network (mDNS), Wi-Fi Direct, Bluetooth, Tor (SOCKS5 + .onion)
• TransportManager with automatic priority-based failover
• MeshRelay for multi-hop message delivery across peers

Mobile (apps/android/, apps/ios/, apps/mobile/):

• Rust FFI bindings for Android (JNI) and iOS (Swift bridge)
• React Native shared UI layer

Infrastructure:

• Docker Compose with PostgreSQL 16, Redis 7, Nginx, server
• GitLab CI/CD pipeline with build artifacts (.deb, Docker image)

By the Numbers

Counted from tracked source at the v0.10.2 tag via git ls-files and wc. Excludes generated lockfiles (package-lock.json, Cargo.lock), build output (target/, dist/), and dependencies (node_modules/).

Source code

Documentation

Tests

Repository layout

Project history: 202 commits on main/develop since project start, across six release tags (v0.7.0, v0.8.0, v0.9.0, v0.10.0, v0.10.1, v0.10.2).

Documentation

Contributing

Contributions are welcome. VAULTEX follows a GitFlow branching model with Conventional Commits. All changes targeting cryptographic code, server middleware, or authentication require Security Engineer review.

See CONTRIBUTING.md for full instructions on setting up your environment, branch naming, commit format, and the merge request process.

License

This project is licensed under the GNU General Public License v3.0.

Security

VAULTEX takes security seriously. If you discover a security vulnerability, please report it responsibly:

• Do not open a public issue for security vulnerabilities.
• Use GitLab's confidential issue feature or contact the maintainers directly.
• Include steps to reproduce, potential impact, and any suggested remediation.

All changes to cryptographic code (crates/vaultex-crypto/), server authentication middleware, and crypto integration paths undergo mandatory security review before merge. The project maintains a Security Audit Checklist and plans a formal security audit prior to public release.