feat: add folder_prefix support to keyring and pass providers

Allow sharing secrets across projects by customizing the storage path
via URI (e.g., keyring://secretspec/shared/{profile}/{key}), matching
the existing OnePassword and LastPass behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: domenkozar

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Keyring and pass providers now support `folder_prefix` via URI (e.g., `keyring://secretspec/shared/{profile}/{key}`)
+  to share secrets across projects, matching the existing OnePassword and LastPass behavior
+
 ### Changed
 - Support `XDG_CONFIG_HOME` on macOS by switching from `directories` to `etcetera` crate.
   Existing macOS configs at `~/Library/Application Support/secretspec/` are automatically

docs/src/content/docs/providers/keyring.md

@@ -55,4 +55,24 @@ $ secretspec run -- npm start
 # Use with profiles
 $ secretspec set API_KEY --profile production
 $ secretspec run --profile production -- npm start
-```
+```
+
+## Shared Secrets
+
+By default, secrets are stored under `secretspec/{project}/{profile}/{key}`, which isolates them per project. To share secrets across projects, use a custom folder prefix via the URI:
+
+```toml
+# ~/.config/secretspec/config.toml
+[providers]
+shared = "keyring://secretspec/shared/{profile}/{key}"
+```
+
+The URI supports `{project}`, `{profile}`, and `{key}` placeholders. By omitting `{project}`, multiple projects can read and write the same keyring entry:
+
+```toml
+# secretspec.toml (in project-A and project-B)
+[profiles.default]
+ARTIFACTORY_USER = { description = "Artifactory user", providers = ["shared"] }
+```
+
+Both projects will resolve `ARTIFACTORY_USER` from keyring service `secretspec/shared/default/ARTIFACTORY_USER`.

docs/src/content/docs/providers/pass.md

@@ -57,3 +57,23 @@ For example, with project "myapp" and profile "default":
 $ pass show secretspec/myapp/default/DATABASE_URL
 postgresql://localhost/mydb
 ```
+
+## Shared Secrets
+
+By default, secrets are stored under `secretspec/{project}/{profile}/{key}`, which isolates them per project. To share secrets across projects, use a custom folder prefix via the URI:
+
+```toml
+# ~/.config/secretspec/config.toml
+[providers]
+shared = "pass://secretspec/shared/{profile}/{key}"
+```
+
+The URI supports `{project}`, `{profile}`, and `{key}` placeholders. By omitting `{project}`, multiple projects can read and write the same pass entry:
+
+```toml
+# secretspec.toml (in project-A and project-B)
+[profiles.default]
+ARTIFACTORY_USER = { description = "Artifactory user", providers = ["shared"] }
+```
+
+Both projects will resolve `ARTIFACTORY_USER` from pass entry `secretspec/shared/default/ARTIFACTORY_USER`.

secretspec/src/provider/keyring.rs

@@ -9,18 +9,30 @@ use url::Url;
 ///
 /// This struct holds configuration options for the keyring provider,
 /// which stores secrets in the system's native keychain service.
-/// Currently, no additional configuration is required as the provider
-/// uses sensible defaults for all platforms.
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct KeyringConfig {}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct KeyringConfig {
+    /// Optional folder prefix format string for organizing secrets in the keyring.
+    ///
+    /// Supports placeholders: {project}, {profile}, and {key}.
+    /// Defaults to "secretspec/{project}/{profile}/{key}" if not specified.
+    pub folder_prefix: Option<String>,
+}
+
+impl Default for KeyringConfig {
+    fn default() -> Self {
+        Self {
+            folder_prefix: None,
+        }
+    }
+}
 
 impl TryFrom<&Url> for KeyringConfig {
     type Error = SecretSpecError;
 
     /// Creates a new KeyringConfig from a URL.
     ///
-    /// The URL must have the scheme "keyring" (e.g., "keyring://").
-    /// Currently, no additional parameters are supported in the URL.
+    /// The URL must have the scheme "keyring" (e.g., "keyring://" or
+    /// "keyring://secretspec/shared/{profile}/{key}").
     ///
     /// # Examples
     ///
@@ -38,12 +50,20 @@ impl TryFrom<&Url> for KeyringConfig {
             )));
         }
 
-        Ok(Self::default())
+        let mut config = Self::default();
+
+        if let Some(host) = url.host_str() {
+            let path = url.path();
+            // Percent-decode so placeholders like {profile} and {key} survive URL parsing
+            let raw = format!("{}{}", host, path);
+            let decoded = raw.replace("%7B", "{").replace("%7D", "}");
+            config.folder_prefix = Some(decoded);
+        }
+
+        Ok(config)
     }
 }
 
-impl KeyringConfig {}
-
 /// Provider for storing secrets in the system keychain.
 ///
 /// The KeyringProvider uses the operating system's native secure credential
@@ -52,13 +72,12 @@ impl KeyringConfig {}
 /// - Windows: Credential Manager
 /// - Linux: Secret Service API (via libsecret)
 ///
-/// Secrets are stored with a hierarchical key structure:
-/// `secretspec/{project}/{profile}/{key}`
+/// Secrets are stored with a hierarchical key structure using a configurable
+/// format string that defaults to: `secretspec/{project}/{profile}/{key}`.
 ///
 /// This ensures secrets are properly namespaced by project and profile,
 /// preventing conflicts between different projects or environments.
 pub struct KeyringProvider {
-    #[allow(dead_code)]
     config: KeyringConfig,
 }
 
@@ -68,7 +87,7 @@ crate::register_provider! {
     name: "keyring",
     description: "Uses system keychain (Recommended)",
     schemes: ["keyring"],
-    examples: ["keyring://"],
+    examples: ["keyring://", "keyring://secretspec/shared/{profile}/{key}"],
 }
 
 impl KeyringProvider {
@@ -84,6 +103,23 @@ impl KeyringProvider {
     pub fn new(config: KeyringConfig) -> Self {
         Self { config }
     }
+
+    /// Formats the service name for a secret in the keyring.
+    ///
+    /// Uses folder_prefix as a format string with {project}, {profile}, and {key} placeholders.
+    /// Defaults to "secretspec/{project}/{profile}/{key}" if not configured.
+    fn format_service(&self, project: &str, profile: &str, key: &str) -> String {
+        let format_string = self
+            .config
+            .folder_prefix
+            .as_deref()
+            .unwrap_or("secretspec/{project}/{profile}/{key}");
+
+        format_string
+            .replace("{project}", project)
+            .replace("{profile}", profile)
+            .replace("{key}", key)
+    }
 }
 
 impl Provider for KeyringProvider {
@@ -92,30 +128,21 @@ impl Provider for KeyringProvider {
     }
 
     fn uri(&self) -> String {
-        // Keyring can be just "keyring" or "keyring://"
-        "keyring".to_string()
+        if let Some(ref prefix) = self.config.folder_prefix {
+            format!("keyring://{}", prefix)
+        } else {
+            "keyring".to_string()
+        }
     }
 
     /// Retrieves a secret from the system keychain.
     ///
-    /// The secret is looked up using a hierarchical key structure:
-    /// `secretspec/{project}/{profile}/{key}`
+    /// The secret is looked up using a hierarchical key structure determined
+    /// by the folder_prefix format string (defaults to `secretspec/{project}/{profile}/{key}`).
     ///
     /// The current system username is used as the account identifier.
-    ///
-    /// # Arguments
-    ///
-    /// * `project` - The project name
-    /// * `key` - The secret key to retrieve
-    /// * `profile` - The profile/environment name
-    ///
-    /// # Returns
-    ///
-    /// * `Ok(Some(String))` - The secret value if found
-    /// * `Ok(None)` - If the secret doesn't exist
-    /// * `Err` - If there was an error accessing the keychain
     fn get(&self, project: &str, key: &str, profile: &str) -> Result<Option<SecretString>> {
-        let service = format!("secretspec/{}/{}/{}", project, profile, key);
+        let service = self.format_service(project, profile, key);
         let username = whoami::username()
             .map_err(|e| SecretSpecError::ProviderOperationFailed(e.to_string()))?;
         let entry = Entry::new(&service, &username)?;
@@ -128,25 +155,13 @@ impl Provider for KeyringProvider {
 
     /// Stores a secret in the system keychain.
     ///
-    /// The secret is stored with a hierarchical key structure:
-    /// `secretspec/{project}/{profile}/{key}`
+    /// The secret is stored with a hierarchical key structure determined
+    /// by the folder_prefix format string (defaults to `secretspec/{project}/{profile}/{key}`).
     ///
     /// The current system username is used as the account identifier.
     /// If a secret already exists with the same key, it will be overwritten.
-    ///
-    /// # Arguments
-    ///
-    /// * `project` - The project name
-    /// * `key` - The secret key to store
-    /// * `value` - The secret value to store
-    /// * `profile` - The profile/environment name
-    ///
-    /// # Returns
-    ///
-    /// * `Ok(())` - If the secret was stored successfully
-    /// * `Err` - If there was an error accessing the keychain
     fn set(&self, project: &str, key: &str, value: &SecretString, profile: &str) -> Result<()> {
-        let service = format!("secretspec/{}/{}/{}", project, profile, key);
+        let service = self.format_service(project, profile, key);
         let username = whoami::username()
             .map_err(|e| SecretSpecError::ProviderOperationFailed(e.to_string()))?;
         let entry = Entry::new(&service, &username)?;

secretspec/src/provider/pass.rs

@@ -9,17 +9,31 @@ use url::Url;
 ///
 /// This struct holds configuration options for the pass provider.
 /// Pass stores secrets as GPG-encrypted files using the Unix password
-/// manager in a hierarchical structure: `secretspec/{project}/{profile}/{key}`.
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct PassConfig {}
+/// manager in a hierarchical structure.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PassConfig {
+    /// Optional folder prefix format string for organizing secrets in pass.
+    ///
+    /// Supports placeholders: {project}, {profile}, and {key}.
+    /// Defaults to "secretspec/{project}/{profile}/{key}" if not specified.
+    pub folder_prefix: Option<String>,
+}
+
+impl Default for PassConfig {
+    fn default() -> Self {
+        Self {
+            folder_prefix: None,
+        }
+    }
+}
 
 impl TryFrom<&Url> for PassConfig {
     type Error = SecretSpecError;
 
     /// Creates a PassConfig from a URL.
     ///
-    /// The URL must have the scheme "pass" (e.g., "pass://").
-    /// Currently, no additional parameters are supported in the URL.
+    /// The URL must have the scheme "pass" (e.g., "pass://" or
+    /// "pass://secretspec/shared/{profile}/{key}").
     fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
         if url.scheme() != "pass" {
             return Err(SecretSpecError::ProviderOperationFailed(format!(
@@ -28,7 +42,17 @@ impl TryFrom<&Url> for PassConfig {
             )));
         }
 
-        Ok(Self::default())
+        let mut config = Self::default();
+
+        if let Some(host) = url.host_str() {
+            let path = url.path();
+            // Percent-decode so placeholders like {profile} and {key} survive URL parsing
+            let raw = format!("{}{}", host, path);
+            let decoded = raw.replace("%7B", "{").replace("%7D", "}");
+            config.folder_prefix = Some(decoded);
+        }
+
+        Ok(config)
     }
 }
 
@@ -40,8 +64,6 @@ impl TryFrom<Url> for PassConfig {
     }
 }
 
-impl PassConfig {}
-
 /// Provider for managing secrets with pass (password-store).
 ///
 /// The PassProvider uses the Unix password manager `pass`, which stores
@@ -61,7 +83,6 @@ impl PassConfig {}
 /// - GPG must be configured with appropriate keys
 /// - The password store must be initialized (`pass init`)
 pub struct PassProvider {
-    #[allow(dead_code)]
     config: PassConfig,
 }
 
@@ -71,7 +92,7 @@ crate::register_provider! {
     name: "pass",
     description: "Unix password manager with GPG encryption",
     schemes: ["pass"],
-    examples: ["pass://"],
+    examples: ["pass://", "pass://secretspec/shared/{profile}/{key}"],
 }
 
 impl PassProvider {
@@ -82,9 +103,19 @@ impl PassProvider {
 
     /// Formats the entry name for a secret.
     ///
-    /// Creates a hierarchical path: `secretspec/{project}/{profile}/{key}`
+    /// Uses folder_prefix as a format string with {project}, {profile}, and {key} placeholders.
+    /// Defaults to "secretspec/{project}/{profile}/{key}" if not configured.
     fn format_entry_name(&self, project: &str, profile: &str, key: &str) -> String {
-        format!("secretspec/{}/{}/{}", project, profile, key)
+        let format_string = self
+            .config
+            .folder_prefix
+            .as_deref()
+            .unwrap_or("secretspec/{project}/{profile}/{key}");
+
+        format_string
+            .replace("{project}", project)
+            .replace("{profile}", profile)
+            .replace("{key}", key)
     }
 }
 
@@ -94,7 +125,11 @@ impl Provider for PassProvider {
     }
 
     fn uri(&self) -> String {
-        "pass".to_string()
+        if let Some(ref prefix) = self.config.folder_prefix {
+            format!("pass://{}", prefix)
+        } else {
+            "pass".to_string()
+        }
     }
 
     /// Retrieves a secret from the password store.

secretspec/src/provider/tests.rs

@@ -452,6 +452,35 @@ mod integration_tests {
         assert_eq!(provider.uri(), "pass");
     }
 
+    #[test]
+    fn test_keyring_with_folder_prefix() {
+        let provider =
+            Box::<dyn Provider>::try_from("keyring://secretspec/shared/{profile}/{key}").unwrap();
+        assert_eq!(provider.name(), "keyring");
+        assert_eq!(
+            provider.uri(),
+            "keyring://secretspec/shared/{profile}/{key}"
+        );
+
+        // Without folder_prefix, should use default URI
+        let provider = Box::<dyn Provider>::try_from("keyring://").unwrap();
+        assert_eq!(provider.name(), "keyring");
+        assert_eq!(provider.uri(), "keyring");
+    }
+
+    #[test]
+    fn test_pass_with_folder_prefix() {
+        let provider =
+            Box::<dyn Provider>::try_from("pass://secretspec/shared/{profile}/{key}").unwrap();
+        assert_eq!(provider.name(), "pass");
+        assert_eq!(provider.uri(), "pass://secretspec/shared/{profile}/{key}");
+
+        // Without folder_prefix, should use default URI
+        let provider = Box::<dyn Provider>::try_from("pass://").unwrap();
+        assert_eq!(provider.name(), "pass");
+        assert_eq!(provider.uri(), "pass");
+    }
+
     #[test]
     fn test_pass_provider_allows_set() {
         let provider = Box::<dyn Provider>::try_from("pass").unwrap();