Skip to content

CONTEXT.md

Latest commit

 

History

History
71 lines (63 loc) · 16 KB

CONTEXT.md

File metadata and controls

71 lines (63 loc) · 16 KB
Raw

Omarchy Bitwarden Plugin Domain Model

Core Concepts & Glossary

Backend & Execution Engine (omawarden)

  • Native Backend (omawarden): Standalone pure Rust helper binary and resident Unix Domain Socket daemon providing sub-millisecond in-memory vault indexing, zero external runtime dependencies (no Python or Node.js runtime needed), memory-hardened secret scrubbing (zeroize), and Wayland desktop integration (see docs/adr/0003-omawarden-rust-native-helper-and-daemon-architecture.md).
  • Toolchain & Versioning: Managed via mise (.mise.toml) and standard Cargo workspaces. Built-in GIT_HASH and BUILD_DATE embedded at compile-time with automated version checking (omawarden -V).
  • Daemon Lifecycle & Auto-Upgrade: Resident daemon listening on /run/user/<UID>/omawarden.sock. The CLI verifies the daemon's running Git commit hash on every command invocation; outdated daemons are gracefully terminated via {"action": "stop"} and smoothly re-spawned with the latest binary version.
  • System Package Distribution & Path Resolution: Distributed natively as Arch User Repository (AUR) packages: omawarden-bin for official stable releases and omawarden-git for bleeding-edge VCS source builds tracking develop (declaring mandatory runtime dependencies on libsecret and wl-clipboard, with mutual provides and conflicts). On overlay initialization, the frontend dynamically probes for system-wide omawarden in $PATH (command -v omawarden) without local binary fallback. A strict minimum engine version gate (>= 0.8.1) is enforced fail-closed (isEngineVersionSatisfied). If runtime prerequisites are missing or the engine is outdated, the overlay gates entry and presents an onboarding view (components/DependencyCheckView.qml) with one-click terminal package installation targeting omawarden so the AUR helper prompts the user to select their preferred provider (see docs/adr/0012-transition-engine-distribution-to-aur.md and docs/adr/0019-aur-git-package-distribution.md).
  • Development Versioning & Pre-release Delivery: Explicit next-version identifiers (e.g., 0.8.0-dev) configured in omawarden/Cargo.toml. Pushes to develop automatically trigger dual-architecture builds (x86_64, aarch64) published to GitHub Pre-releases via a rolling, floating omawarden-dev tag, while omawarden-git on AUR enables native source-based package management. The desktop frontend suppresses regular stable update notifications when running an unreleased -dev engine (see docs/adr/0013-engine-dev-versioning-and-pre-release-delivery.md).
  • Local Development Packaging: Developer workflows supporting testing modalities: offline local Arch binary package creation via mise run pkg-dev [--install] (rendered with [ AUR ] badge), and full local Arch VCS packaging via mise run pkg-git [--install] [--local].

Vault & Session Lifecycle

  • Vault: The encrypted collection of user credentials, folders, organization collections, and attachments synced from a Bitwarden / Vaultwarden server.
  • Server Address (server_url) & Instance Isolation: The base endpoint of the Bitwarden instance (e.g., official cloud https://vault.bitwarden.com or custom self-hosted Vaultwarden instance). Updating the configuration to a different server_url automatically triggers instance-isolation cleanup, atomically wiping stale credentials (email, API key client_id, API client_secret), destroying active sessions (tokens and daemon memory), and purging local cache files (data.json, /tmp attachments) to prevent cross-server credential or data contamination (see docs/adr/0008-server-switching-credential-and-cache-invalidation.md).
  • Authentication Modes:
    • Master Password Login: Email + Master Password with PBKDF2/Argon2id client-side key derivation, pluggable 2FA challenge support including Authenticator TOTP and Email 2FA (provider 1) (see docs/adr/0017-email-and-pluggable-2fa-providers.md), WebAuthn / FIDO2 physical security keys (provider 7) with continuous hotplug detection (see docs/adr/0018-webauthn-fido2-security-key-two-factor-authentication.md), and new device email verification (newDeviceOtp) challenge handling (see docs/adr/0016-new-device-verification-otp-authentication.md).
    • API Key Login: Standard OAuth2 client_credentials flow using client_id and client_secret.
  • Vault Status:
    • unauthenticated: Logged out; requires server URL configuration, auth credentials (Email + Master Password or API Key client_id/client_secret).
    • locked: Logged in, but vault encrypted; requires Master Password to unlock and load in-memory decrypted cache.
    • unlocked: Decryption session active, stored in System Keyring, in-memory search index populated.

Keyring & Security Policies

  • System Keyring & Credential Persistence: Secret storage backend (via FreeDesktop Secret Service / secret-tool / D-Bus) used to securely persist access_token, refresh_token, and API client_secret across app invocations, ensuring data.json on disk remains a pure zero-knowledge ciphertext store (see docs/adr/0007-keyring-credential-persistence-and-silent-reauth.md).
  • Silent Background Re-authentication: Seamless re-authentication via API client_secret or OAuth2 refresh_token when tokens expire (~2h TTL) or return 401/403, preventing disruption during background sync.
  • Atomic Credential Erasure: Calling auth logout or updating to a different server_url triggers clear_all() across all service=omarchy-bitwarden entries in the OS keyring and purges local storage (see docs/adr/0008-server-switching-credential-and-cache-invalidation.md).
  • Zero-Leakage Memory Policy: Sensitive cryptographic keys (SymmetricCryptoKey) and intermediate hashes derive Zeroize and #[zeroize(drop)] to enforce volatile memory destruction on drop.
  • Zero-Argv / Zero-Environ Security Seam: To prevent credential leakage across Linux processes (/proc/<pid>/cmdline and /proc/<pid>/environ), secrets (Master Passwords, API Secrets, TOTP seeds, Clipboard text) are delivered exclusively through protected stdin streams or 0600 Unix Domain Sockets.
  • Strict File & Socket Permissions & XDG Data Isolation: Disk storage (data.json) resides outside the inotify-watched plugin directory at $XDG_DATA_HOME/omawarden/data.json (defaulting to ~/.local/share/omawarden/data.json), and configuration (config.json) resides at $XDG_CONFIG_HOME/omawarden/config.json (defaulting to ~/.config/omawarden/config.json), both featuring automatic transparent migration from legacy plugin directories to prevent hot-reload loops, and enforcing 0600 owner-only permissions along with the daemon Unix socket (omawarden.sock) (see docs/adr/0015-xdg-data-storage-location-and-migration.md and docs/adr/0020-xdg-config-location-and-migration.md).
  • Daemon In-Memory Cache & Scrubbing: Decrypted vault items and keys are held exclusively in daemon memory while unlocked. Manual auth lock, auth logout, idle timeouts, or screen-lock events immediately trigger {"action": "lock"} IPC to purge all decrypted items and keys from memory.
  • Clipboard Guard: Ephemeral clipboard management using Wayland native wl-copy with automatic 30-second TTL cleanup for copied passwords, PINs, card numbers, and TOTPs, ensuring sensitive card numbers are sanitized into pure unsegmented digit strings prior to clipboard delivery.
  • Website Icon Privacy & Endpoint Isolation: Resolution policy governing website favicon retrieval. Official Bitwarden cloud instances query https://icons.bitwarden.net/{domain}/icon.png. Self-hosted instances (e.g. Vaultwarden or self-hosted Bitwarden) strictly query the user's configured server endpoint (${server_root}/icons/{domain}/icon.png), preventing leakage of intranet or private domain names to public third-party services. If self-hosted icon retrieval fails (such as on air-gapped networks or when server icon proxying is disabled), the UI fails closed to default category icons (\uf084) and never falls back to public servers (see docs/adr/0014-self-hosted-icon-service-endpoint-and-privacy-isolation.md).
  • TLS Trust Architecture & Native OS Trust Store: Outbound HTTPS connections across API requests, attachment streaming, and server health checks resolve trust anchors through the platform-native root certificate store (rustls-tls-native-roots). Any private, corporate, or homelab Certificate Authority (CA) trusted system-wide by Arch Linux / Omarchy (e.g. via trust anchor / /etc/ca-certificates/) is automatically accepted out of the box with zero configuration, while maintaining strict fail-closed TLS verification and rejecting insecure bypass switches (insecure_tls) (see docs/adr/0021-tls-system-trust-store-and-rejection-of-insecure-mode.md).
  • Dynamic Dual-Tier User-Agent & Client Identity: Outbound HTTP requests differentiate client identification between interactive terminal CLI invocations (Omawarden/<engine_ver> (Bitwarden/2026.7.0; Linux)) and desktop UI overlay invocations (Omarchy_Bitwarden/<plugin_ver> (Omawarden/<engine_ver>; Bitwarden/2026.7.0; Linux)). Detection occurs automatically without QML frontend changes: non-interactive sub-process pipes trigger a safe probe of the local plugin manifest (~/.config/omarchy/plugins/icyleaf.bitwarden/manifest.json), passing client metadata in-memory over Unix domain socket IPC to the daemon. Strict character whitelisting ([0-9a-zA-Z._-]{1,32}) rejects header injection (CRLF), and missing or invalid manifests fail-safe to pure CLI identity (see docs/adr/0022-dynamic-dual-tier-user-agent-identification.md).

Cryptographic Hierarchy & Organization Domain

  • User Master Key: Derived via PBKDF2-HMAC-SHA256 or Argon2id, used to decrypt the User Symmetric Key (enc_user_key).
  • User RSA Private Key: Decrypted from enc_private_key (supporting PKCS#8 DER, PKCS#1 DER, Base64-encoded strings, and PEM formats).
  • Organizations & Collections:
    • Organization Symmetric Keys (organizations[].key) are decrypted via RSA-OAEP-SHA1 (Rsa2048_OaepSha1_B64, Type 4) using the user's RSA private key.
    • Organization items link to organization_id, organization_name, and collection_ids, displayed with [🏢 Org Name] badges in list and inspector views.
  • Folders: Decrypted folder names (folder_id, folder_name) associated with vault items, displayed with [📁 Folder Name] badges.
  • Soft-Delete Filtering: Items flagged with deletedDate (Trash / Recycle Bin) are filtered out automatically during sync and search.

Vault Item Domain & Type Isolation

  • Vault Item: A single entity stored in the vault, categorized by type with strict type-specific JSON serialization (omitting empty structures for unrelated types):
    • Login: Website/app credentials (Username, Password, URIs, live TOTP countdown, Custom Fields, Password History with Ctrl+H modal).
    • Card: Payment card details (Brand, Cardholder, Number with brand-aware segmented formatting and reveal toggle, Expiration, CVV/Security Code). Card numbers feature brand-aware segmented display (e.g. 4-6-5 for Amex, 4-6-4 for Diners, 4-4-4-4 for standard cards) across both masked and revealed states, while clipboard copies strictly output sanitized pure digits.
    • Identity: Personal identification records (Title, Full Name, Username, Email, Phone, Company, Address, SSN, Passport, License).
    • Secure Note: Encrypted text notes or documentation with dedicated category classification.
    • SSH Key: Private and public key pairs (official Bitwarden Cipher Type 5 with privateKey, publicKey, and keyFingerprint). Supports automated on-the-fly key generation (Ed25519, RSA, ECDSA), file/STDIN import with auto-derived public keys/fingerprints, and export with hardened Unix file permissions (0600/0644) via omawarden ssh-key (see docs/adr/0005-ssh-key-management-lifecycle.md).
    • Attachments: Encrypted binary or text files associated with an item. Downloads resolve signed URLs, decrypt Bitwarden EncArrayBuffer binary blobs ([encType][IV][MAC][Ciphertext]) via AES-256-CBC using resolved attachment.key or cipher_key, and support both in-overlay popup previews (images and text) and external default app viewing via xdg-open (see docs/adr/0002-vault-item-attachments-lifecycle.md).
  • Vault Index: An in-memory, fast-searchable structured cache of vault items updated upon sync or vault unlock.

Interaction & UI Paradigms

  • Overlay Window: Main search launcher modal summoned by global shortcut (Super+/ or user-defined).
  • Multi-Dimensional Filtering & Scope:
    • Vault Scope (vault_scope): Filters items by vault ownership domain: All Vaults (default), Personal Vault (personal credentials where organization_id == null), or a specific Organization ([🏢 Org Name]). Triggered via the search bar dropdown selector or Ctrl+K.
    • Folder Scope (folder_scope): Filters items assigned to a specific folder: All Folders (default) or a specific Folder ([📁 Folder Name]).
    • Category Tabs (category_scope): Filter bar allowing quick switching across item kinds (All, Login, Card, Identity, Note, SSH).
    • Conjunctive Filter Pipeline: Orthogonal multi-layer query evaluation (Query ∧ Category ∧ VaultScope ∧ FolderScope), enabling precise credential narrowing.
  • Inspector Pane: Side panel rendering details, masked secrets, live TOTP countdown, custom fields, organization/folder tags, attachments, and password history entry.
  • Action Palette (Ctrl+K): Modal listing all contextual operations (Copy Password ↵, Copy TOTP Ctrl+↵, Copy Username Ctrl+U, Toggle Field Visibility Ctrl+T, View Password History Ctrl+H, Open Website Ctrl+O, Filter by Vault/Org, Filter by Folder, Copy Organization Name, Copy Folder Name, Copy Card/Identity attributes, Copy Public/Private Key, View/Download Attachments, Lock Vault Ctrl+L, Sync Ctrl+R).
  • Config & Settings View: Allows user configuration of server_url, identity_url, download_dir, auto_lock_minutes, clipboard_clear_seconds, log_level, show_website_icons, check_updates, and remember_last_search, with real-time CLI readiness indicators and an embedded Logs Viewer.
  • Search State Persistence & Reopen Interaction (remember_last_search): Optional user setting (default: false) that retains the active search query, category, vault/folder scopes, and list selection across overlay dismiss and reopen cycles while the vault remains unlocked. Upon reopening, focus is given to the search input with the cursor positioned at the end and text deselected, allowing immediate character-by-character backspace editing, seamless Up/Down list item navigation, and Esc query clearing. Under all circumstances, modal popups and revealed plaintext secrets are reset upon dismissal, and any vault lock event (manual Ctrl+L, idle timeout, screen lock, logout, server switch) unconditionally wipes the search state to uphold zero-leakage security invariants.
  • Observability & Diagnostics: Dual-channel structured logging across omawarden (stderr) and Quickshell (console.error), featuring module prefixes ([omawarden:cli], [omarchy:ui]), configurable log levels (error by default), zero-knowledge credential and custom server URL redaction, and one-click "Copy Diagnostics" for privacy-safe GitHub issue reporting (see docs/adr/0004-structured-logging-and-diagnostics.md).
  • Prerequisite Onboarding View: If core system packages (omawarden, libsecret, wl-clipboard) are not detected via pacman -Q, the overlay gates normal vault views and displays DependencyCheckView, allowing users to install missing dependencies with one click via their preferred AUR helper (paru, yay, pacman) in an Omarchy floating terminal window.

Boundaries & Non-Goals

  • Non-Goals: Full vault item creation/editing/management (e.g. creating complex cryptographic policies or modifying organization memberships is handled via official Bitwarden web/apps). Focus is on lightning-fast retrieval, search, copying, and secure autofill in the Omarchy desktop.