fix(config): migrate config.json to XDG config directory to prevent shell reload loop (#187)

- Relocate default config file from ~/.config/omarchy/plugins/icyleaf.bitwarden/config.json to ~/.config/omawarden/config.json
- Add support for OMAWARDEN_CONFIG_DIR env var
- Automatically migrate existing config.json from legacy plugin directory with 0600 permissions and clean up stale files
- Document architectural decision in docs/adr/0020-xdg-config-location-and-migration.md and update CONTEXT.md
- Add unit tests verifying default path, legacy migration, and cleanup

Author: icyleaf

CONTEXT.md

@@ -27,7 +27,7 @@
 - **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` with automatic migration from legacy paths) to prevent hot-reload loops, and enforces `0600` owner-only permissions along with the daemon Unix socket (`omawarden.sock`) (see `docs/adr/0015-xdg-data-storage-location-and-migration.md`).
+- **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, and TOTPs.
 - **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`).

docs/adr/0020-xdg-config-location-and-migration.md

@@ -0,0 +1,32 @@
+# ADR 0020: Relocate Configuration File to XDG Config Directory to Prevent Shell Reload Loops
+
+## Status
+Accepted
+
+## Context
+In ADR 0015, the encrypted vault storage `data.json` was relocated from `$XDG_CONFIG_HOME/omarchy/plugins/icyleaf.bitwarden/data.json` to `$XDG_DATA_HOME/omawarden/data.json` to eliminate hot-reload loops triggered by the host Omarchy desktop shell (`services/PluginRegistry.qml`), which actively monitors `$XDG_CONFIG_HOME/omarchy/plugins/` with `inotifywait -m -r -q -e close_write,create,delete,move`.
+
+However, `config.json` remained located inside the watched plugin directory:
+`$XDG_CONFIG_HOME/omarchy/plugins/icyleaf.bitwarden/config.json`
+
+Whenever a user modified preferences in the GUI Settings modal (such as changing the server URL, auto-lock timeout, clipboard TTL, or max attachment size) and clicked Save, `omawarden config set` performed an atomic file write (`fs_util::atomic_write_str`) over `config.json`. Because this atomic write creates a temporary file and renames it inside the plugin directory, `inotifywait` immediately detected the modification, causing `omarchy-shell` to misinterpret the event as a plugin code update and trigger `shell.reloadPlugins()`. This tore down panels, widgets, and services, causing visual UI restarts and desktop panel flickering.
+
+In addition, storing application configuration inside a third-party desktop plugin repository violates the Freedesktop XDG Base Directory Specification, which specifies `$XDG_CONFIG_HOME` for application-specific configuration files.
+
+## Decision
+1. **Relocate Default Configuration to `$XDG_CONFIG_HOME/omawarden/config.json`**:
+   - `ConfigManager::default()` now resolves `config.json` to `$XDG_CONFIG_HOME/omawarden/config.json` (defaulting to `$HOME/.config/omawarden/config.json`).
+   - This location resides completely outside the inotify-monitored Omarchy plugin hierarchy.
+
+2. **Environment Variable Override (`OMAWARDEN_CONFIG_DIR`)**:
+   - `ConfigManager` checks the `OMAWARDEN_CONFIG_DIR` environment variable before falling back to `XDG_CONFIG_HOME`, allowing integration tests, containerized environments, and custom setups to override the configuration path.
+
+3. **Transparent Legacy Migration**:
+   - Upon initialization, `ConfigManager` checks whether a legacy file exists at `$XDG_CONFIG_HOME/omarchy/plugins/icyleaf.bitwarden/config.json`.
+   - If the legacy file exists and the new target does not, `omawarden` atomically moves the file, ensures the parent directory has `0700` permissions, enforces `0600` permissions on the target, and removes the legacy file.
+   - If the target already exists, stale legacy files in the plugin directory are purged to avoid residual inotify events.
+
+## Consequences
+- **Elimination of Reload Loops on Settings Save**: Saving settings in the UI never touches the watched `omarchy/plugins` directory and no longer triggers Omarchy Shell plugin reloads or panel flickering.
+- **XDG Specification Compliance**: Clean separation between plugin source code (`$XDG_CONFIG_HOME/omarchy/plugins/icyleaf.bitwarden/`) and application configuration (`$XDG_CONFIG_HOME/omawarden/config.json`).
+- **Zero Disruption for Existing Users**: Automatic migration preserves existing user configurations (custom server URLs, remember email settings, timeout intervals, etc.) seamlessly.

omawarden/src/attachment.rs

@@ -1442,13 +1442,9 @@ mod tests {
 
         // Set up temporary config directory with 1MB max_attachment_size_mb
         let config_dir = tempfile::tempdir().unwrap();
-        let plugin_dir = config_dir
-            .path()
-            .join("omarchy")
-            .join("plugins")
-            .join("icyleaf.bitwarden");
-        std::fs::create_dir_all(&plugin_dir).unwrap();
-        let config_json = plugin_dir.join("config.json");
+        let cfg_dir = config_dir.path().join("omawarden");
+        std::fs::create_dir_all(&cfg_dir).unwrap();
+        let config_json = cfg_dir.join("config.json");
         std::fs::write(&config_json, r#"{"max_attachment_size_mb": 1}"#).unwrap();
 
         // Set up temporary data directory with data.json pointing to our mock server

omawarden/src/config.rs

@@ -1,8 +1,10 @@
 use serde::{Deserialize, Serialize};
 use std::env;
 use std::fs;
+use std::os::unix::fs::PermissionsExt;
 use std::path::{Path, PathBuf};
 
+pub const DEFAULT_CONFIG_FILENAME: &str = "config.json";
 pub const DEFAULT_SERVER_URL: &str = "https://vault.bitwarden.com";
 pub const DEFAULT_DOWNLOAD_DIR: &str = "~/Downloads";
 pub const DEFAULT_AUTO_LOCK_MINUTES: i64 = 15;
@@ -101,6 +103,59 @@ pub struct ConfigManager {
     pub config_path: PathBuf,
 }
 
+pub fn resolve_legacy_config_path() -> PathBuf {
+    let xdg_config = env::var("XDG_CONFIG_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|_| {
+            let home = env::var("HOME").unwrap_or_else(|_| ".".to_string());
+            PathBuf::from(home).join(".config")
+        });
+    xdg_config
+        .join("omarchy")
+        .join("plugins")
+        .join("icyleaf.bitwarden")
+        .join(DEFAULT_CONFIG_FILENAME)
+}
+
+pub fn migrate_legacy_config_file(legacy_path: &Path, target_path: &Path) {
+    if legacy_path != target_path && legacy_path.exists() {
+        if !target_path.exists() {
+            if let Some(parent) = target_path.parent() {
+                let _ = crate::fs_util::create_secure_dir_all(parent, 0o700);
+            }
+            if fs::rename(legacy_path, target_path).is_err()
+                && fs::copy(legacy_path, target_path).is_ok()
+            {
+                let _ = fs::remove_file(legacy_path);
+            }
+            let _ = fs::set_permissions(target_path, fs::Permissions::from_mode(0o600));
+        } else {
+            let _ = fs::remove_file(legacy_path);
+        }
+    }
+}
+
+pub fn resolve_default_config_path() -> PathBuf {
+    if let Ok(custom_dir) = env::var("OMAWARDEN_CONFIG_DIR") {
+        if !custom_dir.trim().is_empty() {
+            return PathBuf::from(custom_dir.trim()).join(DEFAULT_CONFIG_FILENAME);
+        }
+    }
+
+    let xdg_config = env::var("XDG_CONFIG_HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|_| {
+            let home = env::var("HOME").unwrap_or_else(|_| ".".to_string());
+            PathBuf::from(home).join(".config")
+        });
+    let target_path = xdg_config.join("omawarden").join(DEFAULT_CONFIG_FILENAME);
+    let legacy_path = resolve_legacy_config_path();
+
+    migrate_legacy_config_file(&legacy_path, &target_path);
+
+    target_path
+}
+
 impl Default for ConfigManager {
     fn default() -> Self {
         Self::new(None)
@@ -111,19 +166,7 @@ impl ConfigManager {
     pub fn new(custom_path: Option<&Path>) -> Self {
         let config_path = match custom_path {
             Some(p) => p.to_path_buf(),
-            None => {
-                let xdg_config = env::var("XDG_CONFIG_HOME")
-                    .map(PathBuf::from)
-                    .unwrap_or_else(|_| {
-                        let home = env::var("HOME").unwrap_or_else(|_| ".".to_string());
-                        PathBuf::from(home).join(".config")
-                    });
-                xdg_config
-                    .join("omarchy")
-                    .join("plugins")
-                    .join("icyleaf.bitwarden")
-                    .join("config.json")
-            }
+            None => resolve_default_config_path(),
         };
         Self { config_path }
     }
@@ -821,4 +864,80 @@ esac
         assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);
         assert!(err.to_string().contains("Remote servers must use HTTPS"));
     }
+
+    #[test]
+    fn test_default_config_path_not_in_watched_plugin_directory() {
+        let config_mgr = ConfigManager::default();
+        let path_str = config_mgr.config_path.to_string_lossy();
+        assert!(
+            !path_str.contains("omarchy/plugins"),
+            "Config file path must not reside inside watched omarchy/plugins directory, was: {}",
+            path_str
+        );
+        assert!(
+            path_str.ends_with("omawarden/config.json"),
+            "Config file path must end with omawarden/config.json, was: {}",
+            path_str
+        );
+    }
+
+    #[test]
+    fn test_migrate_legacy_config_file_moves_existing_data() {
+        let dir = tempdir().unwrap();
+        let legacy_dir = dir.path().join("legacy");
+        fs::create_dir_all(&legacy_dir).unwrap();
+        let legacy_file = legacy_dir.join("config.json");
+        fs::write(
+            &legacy_file,
+            "{\"server_url\":\"https://vault.example.com\"}",
+        )
+        .unwrap();
+
+        let target_dir = dir.path().join("target");
+        let target_file = target_dir.join("config.json");
+
+        assert!(legacy_file.exists());
+        assert!(!target_file.exists());
+
+        migrate_legacy_config_file(&legacy_file, &target_file);
+
+        assert!(
+            !legacy_file.exists(),
+            "Legacy config file must be removed after migration"
+        );
+        assert!(
+            target_file.exists(),
+            "Target config file must exist after migration"
+        );
+
+        let content = fs::read_to_string(&target_file).unwrap();
+        assert_eq!(content, "{\"server_url\":\"https://vault.example.com\"}");
+
+        let metadata = fs::metadata(&target_file).unwrap();
+        let mode = metadata.permissions().mode() & 0o777;
+        assert_eq!(
+            mode, 0o600,
+            "Migrated config file must have 0600 permissions"
+        );
+    }
+
+    #[test]
+    fn test_migrate_legacy_config_cleans_up_when_target_already_exists() {
+        let dir = tempdir().unwrap();
+        let legacy_file = dir.path().join("legacy.json");
+        fs::write(&legacy_file, "{\"old\":true}").unwrap();
+
+        let target_file = dir.path().join("target.json");
+        fs::write(&target_file, "{\"new\":true}").unwrap();
+
+        migrate_legacy_config_file(&legacy_file, &target_file);
+
+        assert!(
+            !legacy_file.exists(),
+            "Stale legacy config file must be deleted when target already exists"
+        );
+        assert!(target_file.exists());
+        let content = fs::read_to_string(&target_file).unwrap();
+        assert_eq!(content, "{\"new\":true}");
+    }
 }