omarchy-bitwarden

A blazing fast, zero-bloat, and security-first Bitwarden / Vaultwarden overlay for Omarchy Shell on Hyprland.

Powered by a dedicated pure Rust engine (omawarden), omarchy-bitwarden delivers sub-millisecond credential lookups, minimal memory overhead, and rigorous process isolation—designed from the ground up to replace heavy Electron apps and sluggish Node CLI tooling with a native, Spotlight-style keyboard workflow.

---

Why omarchy-bitwarden?

Dimension	omarchy-bitwarden (omawarden)	Official Desktop App (Electron)	Official CLI (bw)
Response Latency	Sub-millisecond (resident in-memory IPC socket)	Slow UI render (1.5s - 3s)	Heavy Node.js startup delay
Memory Footprint	Lightweight daemon (~10MB base / ~60-80MB with Argon2id)	200MB - 400MB+ Chromium bloat	Transient, high peak memory
Process Security	Zero-leakage (protected stdin & 0600 socket)	Broad webview memory exposure	Secrets prone to argv/ps snooping
Token & Secret Storage	System Keyring Isolation (0 plaintext tokens in local cache)	Desktop Keychain / Electron store	Stored in plaintext cache file or relies on insecure, leak-prone BW_SESSION env export
Local Data Caching	Zero-Knowledge Ciphertext Cache (fast offline search, no tokens)	Local cache file mixed with session tokens	Local cache file mixed with session tokens
Token Expiry Handling	Master Password Unlock Only (Keyring renews tokens silently; never forces API Key re-login)	Desktop app preserves login; prompts for master password	Hard 2-hr expiry (Session expired); forces manual CLI re-login
Lock-Screen Sync	Native daemon auto-detection (Omarchy lock, Hyprlock, D-Bus/logind, sleep)	App idle timeout only	None (manual lock required)
Runtime Dependencies	100% standalone binary (Zero external deps)	Full Chromium/Node runtime	Node.js environment required

Why omawarden instead of rbw?

rbw is an outstanding unofficial Rust CLI client in the Linux ecosystem that pioneered a zero-knowledge resident daemon architecture, serving as a major inspiration for omawarden. Both tools uphold high standards for cryptographic memory safety, featuring physical memory locking (mlock) and immediate memory zeroization (zeroize).

The difference between them is not "CLI vs Desktop", but rather the distinct design trade-offs made across feature completeness, system dependencies, and workflows:

Core Feature Comparison

Dimension	omawarden (Native Engine & Standalone CLI)	rbw (Unofficial Rust CLI)
Item Type Support Depth	First-Class 5 Types: Dedicated extraction flags and structured UI inspection for Logins, Cards (CVV/number), Identities, Notes, and SSH Keys	Primarily targets password and TOTP; viewing cards/identities requires dumping unformatted raw JSON (--raw)
Attachment Decryption	Native: Downloads encrypted blobs and decrypts binary payloads via AES-256-CBC for preview/export	Not supported (see open feature request doy/rbw#130)
Password Revision History	Native: Decrypts and displays item password revision history	Not supported
Organizations & Collections	Full Support: RSA-OAEP-SHA1 Org key unwrapping, Multi-Org & Collection filtering	Basic Support: Focused on personal vault; limited organization & collection support (doy/rbw#351)
SSH Key Capabilities	Keypair Generation & Management: Generates Ed25519/RSA keypairs locally, calculates fingerprints, and exports keys	OpenSSH Agent Proxy: Implements SSH_AUTH_SOCK to sign requests in-memory without keys touching disk (cannot generate keypairs)
Lock Screen Security Integration	Active Zeroize on Lock: Listens to Hyprlock, Omarchy lock, D-Bus logind sleep/lock signals	Passive Idle Timeout: Secrets remain in memory during sleep/lock if idle timer hasn't expired
Authentication & Secret Storage	System Keyring (Secret Service) Integration: Silent background token renewal without interrupting workflow	GnuPG / pinentry Interaction: Standard pinentry (supports TTY pinentry-curses); independent of desktop keyring
GUI IPC Integration	Dedicated Structured JSON IPC Socket: Designed for high-throughput, instant desktop overlay rendering (<1ms)	Plain text stdout/stderr intended for terminal pipelines

Current Limitations of omawarden compared to rbw

In the following scenarios, rbw holds clear advantages, allowing users to choose the best fit for their workflow:

1. Distribution Packaging & Maturity: rbw is packaged in official repositories across Arch, Debian, Fedora, Alpine, NixOS, and macOS Homebrew for one-command installation. omawarden is primarily distributed via AUR and GitHub Releases, and is not yet in other official distribution repositories.
2. Headless & Server Compatibility: rbw paired with pinentry-curses works seamlessly in pure TTYs, servers, or minimal Docker containers without Secret Service daemons. omawarden relies on system Secret Service keyrings for secure token persistence.
3. Real-time OpenSSH Agent Proxy: rbw acts as an active SSH_AUTH_SOCK agent, signing requests in-memory without keys ever touching disk. omawarden does not yet implement the OpenSSH agent protocol and currently focuses on key generation, inspection, and local export.
4. Interactive CLI Editing: rbw provides rbw edit to open $EDITOR and modify vault items directly from the terminal. omawarden currently focuses on read, extract, copy, and generation workflows, and terminal-based vault item mutation is not yet supported (planned for future releases).

---

Keyboard Shortcuts

Shortcut	Description
Enter	Copy primary credential (Password / Card Number / Public Key)
Ctrl + Enter	Copy live TOTP code
Ctrl + U	Copy username
Ctrl + T	Toggle field / secret visibility (passwords, keys, card codes, etc.)
Ctrl + H	Open password history modal for the selected login item
Ctrl + O	Open primary website URL in default browser
Ctrl + K	Open Action Palette (Copy username, TOTP, PIN, Org Name, History, etc.)
Ctrl + ,	Open / Toggle Settings configuration view
Ctrl + L	Manually lock the vault immediately
Ctrl + R	Trigger manual vault sync with Bitwarden server
↓ / ↑	Navigate item list or action options (stops at boundaries)
Tab	Switch category filters (All, Logins, Cards, Identities, Secure Note, SSH Keys)
Alt + V	Switch or cycle Vault / Organization scope filter (All, Personal, Organizations)
Alt + F	Switch or cycle Folder scope filter (All Folders, specific folder)
Esc	Dismiss Action Palette, History modal, Settings, or hide overlay

---

Prerequisites

Ensure the following tools are available on your system:

• omawarden Engine: High-performance Rust backend for Bitwarden (distributed via AUR or GitHub Releases)
• Keyring / Secret Service: secret-tool (libsecret package on Arch/Debian/Fedora)
• Wayland Clipboard: wl-clipboard (wl-copy / wl-paste)

Tip

One-Click Setup: When opening Omarchy Bitwarden for the first time without prerequisites, an interactive Dependency Check view automatically appears, allowing you to install omawarden-bin, libsecret, and wl-clipboard with a single click via an Omarchy floating terminal popup.

---

Installation & Setup

1. Install omawarden Engine (Arch Linux / AUR)

The native engine is officially distributed on AUR in two flavors:

• omawarden-bin (Recommended): Official pre-compiled release binary package.
• omawarden-git: Development VCS package built from the bleeding-edge develop branch.

# Install stable pre-compiled release (recommended)
paru -S omawarden-bin
# or
yay -S omawarden-bin

# Or install bleeding-edge development VCS package
paru -S omawarden-git

(Non-Arch distributions can download pre-built binaries directly from GitHub Releases and place them in your $PATH).

2. Install Plugin via Omarchy CLI

omarchy plugin add https://github.com/icyleaf/omarchy-bitwarden.git --enable

3. Bind Global Hotkey & Window Rule (in ~/.config/hypr/bindings.lua)

-- ~/.config/hypr/bindings.lua
o.bind("SUPER + slash", "Omarchy Bitwarden", "omarchy-shell shell toggle icyleaf.bitwarden")

o.window({ class = "org.quickshell", title = "(Bitwarden)" }, {
  float = true,
  center = true,
  size = { 1152, 768 }
})

Engine Source Badges & Updates

Omarchy Bitwarden seamlessly identifies and manages the active engine source in the Settings modal:

• [ AUR: omawarden-bin ] / [ AUR: omawarden-git ]: Active when installed via pacman/AUR. Offers channel-aware one-click update actions (Update (AUR)) that launch your terminal AUR helper (paru or yay).
• [ System ]: Active on non-Arch distributions when running a standalone pre-compiled binary located in your system $PATH (e.g. /usr/local/bin/omawarden).
• Development Suppression: Development builds (e.g. 0.8.0-dev or VCS revisions from omawarden-git) automatically suppress standard release update notifications to prevent downgrade prompts.

Update & Uninstall

• Update Plugin:

omarchy plugin update icyleaf.bitwarden

• Uninstall Plugin:

killall omawarden
omarchy plugin remove icyleaf.bitwarden

---

Authentication Methods

omarchy-bitwarden supports two authentication methods for connecting to Bitwarden or self-hosted Vaultwarden instances:

1. Master Password Login (+ Comprehensive 2FA Support)

• Default & Direct: Enter your account email and Master Password directly in the overlay login form.
• Comprehensive Two-Factor Authentication (2FA):
  • Authenticator App (TOTP) (Provider 0): Enter your 6-digit verification code from your authenticator app.
  • Email Verification Code (Provider 1): Automatically dispatches an email challenge code with resend capabilities.
  • Hardware Security Key / WebAuthn / FIDO2 (Provider 7): Native hardware security key support (YubiKey, SoloKey, Nitrokey, passkeys). Visual prompt instructs you to touch the physical security key, with support for user presence, user verification, and optional PIN entry.
  • Multi-Provider Switcher: When multiple 2FA methods are active on your account (e.g. Security Key + Authenticator + Email), an interactive provider selector allows switching between methods on the fly, with smart default selection favoring hardware security keys.
• New Device Verification: Seamlessly detects and prompts for email OTP verification challenges when logging in from a newly recognized device.
• Remember Email: Optionally toggle "Remember Email" to prefill your login email address across sessions.

2. API Key Login (Personal API Key)

• Official Bitwarden CLI Standard: Recommended for headless environments or accounts with hardware key / Duo 2FA.
• How to obtain:
  1. Open the Bitwarden Web Vault (or your self-hosted Vaultwarden instance).
  2. Navigate to Settings → Security → Keys tab.
  3. Click View API Key and enter your master password.
  4. Copy your client_id (e.g. user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) and client_secret.
• In Omarchy Overlay: Switch the login tab to API Key, paste your client_id and client_secret, and log in. Once authenticated, subsequent unlocks are completed via your Master Password.
• Keyring Persistence & Silent Renewal: Your client_secret is securely preserved in the system Keyring (never written to disk). When 2-hour access tokens expire, omawarden automatically and silently re-authenticates in the background without interrupting sync or kicking you back to re-login.

---

Security Architecture & Privacy Safeguards

omarchy-bitwarden is engineered with a strict zero-trust, descriptor-isolated security model to protect your credentials from process snooping, memory dumps, and environment leakage on Linux:

flowchart TD
    subgraph Frontend["QML Overlay (Omarchy Shell)"]
        UI_Pwd["Master Password"]
        UI_2FA["2FA Code"]
        UI_API["API Client Secret"]
        UI_TOTP["TOTP Seed"]
        UI_Clip["Clipboard Text"]
    end

    subgraph Seam["Protected Input Seam"]
        P_Stdin["Protected Stdin Pipe (/proc/self/fd/0)\nZero-Argv • Immediate Memory Flush"]
        P_Sock["0600 Unix Domain Socket (/run/user/UID/omawarden.sock)\nPeer UID Verification"]
    end

    subgraph Engine["Pure Rust Engine (omawarden)"]
        direction TB
        Daemon["Resident In-Memory Daemon\nZeroized Memory on Drop (zeroize)"]
        Crypto["Native Cryptography Engine\nPBKDF2 • Argon2id • AES-256-CBC • RSA-OAEP-SHA1"]
        REST["Direct Bitwarden REST/OAuth2 Client\nSilent Background Re-authentication"]
        Clipboard["Ephemeral Wayland Clipboard (wl-copy)"]
    end

    subgraph SecurityStore["Protected System & Disk Stores"]
        Keyring["System Keyring (Secret Service)\nAccess/Refresh Tokens • API Secrets • Session\nZero Plaintext on Disk"]
        Disk["Local Cache File (0600)\nZero-Knowledge Ciphertext Only\nCiphers • Folders • No Bearer Tokens"]
    end

    UI_Pwd -->|Protected Stdin| P_Stdin
    UI_2FA -->|Protected Stdin| P_Stdin
    UI_API -->|Protected Stdin| P_Stdin
    UI_TOTP -->|Protected Stdin| P_Stdin
    UI_Clip -->|Protected Stdin| P_Stdin

    P_Stdin --> Engine
    P_Sock <-->|IPC Queries| Daemon

    Daemon <--> Crypto
    Daemon <--> REST
    Daemon --> Clipboard

    REST <-->|Silent Re-auth / Fetch Tokens| Keyring
    Daemon <-->|Read / Write E2E Ciphertext| Disk
    Daemon <-->|Session & Credentials| Keyring

Loading

Key Security Guarantees:

1. Zero Command-Line (argv) Credential Leakage: Master passwords, client secrets, 2FA codes, TOTP seeds, and clipboard text are never passed as command-line arguments. By delivering all sensitive data exclusively through protected stdin streams or 0600 Unix domain sockets, command line inspection reveals zero sensitive credentials.
2. Zero Process Environment (env) Secret Spillage: API client secrets, passwords, and live session tokens are never exported to process environment variables (/proc/<pid>/environ).
3. Strict Owner-Only File & Socket Permissions (0600) & Peer UID Verification: The local vault cache file, downloaded attachments, and daemon Unix socket (/run/user/<UID>/omawarden.sock) enforce strict 0600 permissions and kernel-level peer UID verification (SO_PEERCRED), isolating endpoints across user accounts. Note: processes running under the same OS user account share UID privileges; process-level sandboxing (e.g. Bubblewrap/Flatpak) is recommended for isolating local untrusted applications.
4. Deterministic Master Key Zeroization (zeroize): All cryptographic keys (SymmetricCryptoKey), derived master keys, and intermediate crypto buffers implement zeroize::ZeroizeOnDrop to overwrite key memory with zeros upon drop. When the vault is locked, all decrypted vault records in daemon memory are immediately cleared and dropped.
5. Native FreeDesktop Secret Service Keyring Lifecycle: Bearer tokens (access_token, refresh_token), API key secrets (client_secret), and active session tokens are stored securely inside the system Keyring (GNOME Keyring / KWallet / KeePassXC) via D-Bus Secret Service protocols. The local cache file is a pure zero-knowledge ciphertext store with zero plaintext bearer tokens or master passwords on disk. Immediate session destruction occurs on lock (Ctrl+L), screen-lock events (hyprlock/swaylock), or idle timeout.
6. Ephemeral Clipboard Auto-Clearing (30s TTL): When copying passwords, TOTP codes, card CVVs, or SSH private keys, sensitive values are piped directly to wl-copy without entering shell logs. A dedicated timer daemon automatically clears the Wayland clipboard after 30 seconds (configurable in Settings).
7. Zero External Runtime Dependencies: 100% pure Rust binary. No external Node.js, Python, or official bw CLI binary is required at runtime.

---

Roadmap

Phase 1: Completed (Fast Lookup & Core Security)

• In-memory caching & sub-millisecond fuzzy search
• Full Argon2id / PBKDF2 / AES-256-CBC / RSA-OAEP native decryption
• Real-time live RFC 6238 TOTP token engine & visual countdown
• Screen-lock auto-lock hook & FreeDesktop Secret Service Keyring integration
• Multi-slot system Keyring credential persistence & silent background re-authentication
• Ephemeral Wayland clipboard manager with 30s auto-clear TTL
• Encrypted binary attachment downloads & inline previews (images & text)
• SSH key management (Ed25519/RSA/ECDSA generation, file import & export)
• Multi-dimensional vault (personal/organization) and folder scope filtering
• Multi-organization & collection key unwrapping with badges
• Action Palette (Ctrl+K) & password history viewer (Ctrl+H)
• FIDO2 / WebAuthn passkey indicator & item creation/update history
• Locked-state background sync (syncing encrypted ciphertext while vault is locked)
• Self-hosted Vaultwarden & personal API key login support
• Comprehensive 2FA support (Authenticator TOTP, Email verification, and native FIDO2 / WebAuthn hardware security keys)
• Official Arch Linux AUR distribution (omawarden-bin, omawarden-git) with UI engine source badges
• Channel-aware update management & floating terminal dependency installer
• Persistent search state (remembers query, category, and selected item across window sessions)
• Dual-channel structured logging & privacy-redacted diagnostics

Phase 2: In Progress / Upcoming (Full Vault Item Lifecycle & Editing)

• Vault item creation (Add Login, Card, Identity, Secure Note)
• Built-in secure password & passphrase generator
• In-place item editing & custom fields modification
• Folder & collection reassignment
• Secure item deletion & soft-delete (Recycle Bin) management

Phase 3: Future

• Wayland auto-type / auto-fill integration (e.g. via ydotool / wtype)
• Quick biometric / PAM / Fingerprint system unlock

---

Contributing

We welcome contributions of all kinds! To ensure smooth collaboration and automated changelog generation, please follow our development workflow:

1. Branch off develop: The main branch is reserved for tagged releases. All active development (features, bug fixes, refactors) branches off develop:

   git checkout develop && git pull
   git checkout -b <type>/<short-description>
   # Types: feat/, fix/, chore/, refactor/, sec/

2. Local Verification: Ensure formatting, lints, and tests pass before committing:

   cd omawarden
   cargo fmt --check
   cargo clippy --all-targets --all-features -- -D warnings
   XDG_RUNTIME_DIR=/tmp cargo test

   (Optional) If you use mise, you can run mise run build or mise run dev-deploy for local testing.
3. Conventional Commits: Write clear commit messages following Conventional Commits (e.g., feat(daemon): ..., fix(ui): ...).
4. Submit PR against develop: Open your Pull Request targeting the develop branch.

For complete development details, please see CONTRIBUTING.md.

---

Credits

omarchy-bitwarden is built upon the great foundation and inspirations of the open-source community:

• Bitwarden CLI (bw): Gratitude to the official Bitwarden team for their protocol specifications, API designs, and comprehensive reference client.
• rbw: Tremendous appreciation to rbw for pioneering a lightning-fast, zero-knowledge resident Rust daemon architecture, which served as a major inspiration for omawarden.

---

License

This project is open-sourced under the MIT License.