Vitra architecture and security
Vitra separates the work that must remain active from the interface that is needed only on demand:
native clipboard adapter
│
▼
authenticated local IPC
│
▼
Rust agent ──> core rules ──> encrypted SQLite history
▲
│ versioned authenticated IPC
▼
on-demand PySide6 / QML UI
The Rust agent owns capture, validation, deduplication, storage, retention, authentication, and platform lifecycle integration. The UI never opens the database and does not watch the clipboard directly.
Platform strategy
Shared domain rules and protocol messages must not depend on Windows, macOS, X11, Wayland, or a UI toolkit. Platform-specific behavior stays behind adapters. This boundary allows each OS to receive its own native capture, credential, startup, shortcut, tray, signing, and packaging behavior without forking storage or domain logic.
PySide6 with Qt Quick is the current delivery UI baseline. A time-boxed Slint benchmark may replace it only if required behavior works and at least two of cold launch, resident memory, and installed size improve by 25% or more. Toolkit experimentation must not delay the working text-history path.
Encrypted history
Each clipboard payload is independently encrypted with XChaCha20-Poly1305, using a fresh random 192-bit nonce and a 256-bit history master key. The stored envelope and database metadata carry explicit format versions. Content type and encryption version are authenticated so ciphertext cannot be moved into an incompatible record context undetected.
The master key is intended to live in the native credential store:
| Platform | Credential backend |
|---|---|
| Linux | Secret Service |
| macOS | Keychain Services |
| Windows | Credential Manager |
Only Linux is currently implemented and exercised end to end. The agent fails closed if it cannot load the key. Losing or resetting the credential entry makes existing encrypted history unrecoverable; generating a replacement key for an existing database would hide that failure and is intentionally forbidden.
The database still reveals metadata including timestamps, item counts, payload lengths, and pin state. Full metadata concealment is outside v1 scope. Search decrypts a bounded candidate set in the agent; a plaintext search index is prohibited.
IPC and capture boundary
Local IPC uses a per-install authentication token and length-bounded messages. The stable local endpoint name separates installations but is not itself an authentication mechanism. The GNOME extension passes clipboard text through a helper’s standard input rather than a command-line argument and does not store the IPC token or database credentials.
Protocol messages are versioned so UI and agent compatibility can be handled explicitly as the project evolves.
Pre-alpha security limits
Encryption is implemented, but Vitra has not completed its threat-model review, independent security review, corruption recovery, packaging hardening, or cross-platform credential validation. Do not use the current build as the sole control protecting highly sensitive clipboard data.
The original version-0 plaintext database was a development artifact, not a supported release format. Resetting that database cannot guarantee secure erasure from SQLite WAL files, filesystem snapshots, backups, or SSD storage. Future released migrations must preserve encrypted data transactionally unless the user explicitly chooses deletion.
The accepted design decisions are maintained upstream in the application architecture and history-encryption ADRs. This portal consolidates their current operational consequences; it does not replace a security audit.