fix: support spaces and special characters in provider URIs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: domenkozar

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Provider URIs now support spaces and special characters in names
+  (e.g., `onepassword://Home Lab`). All providers receive automatically
+  percent-decoded values via a new `ProviderUrl` wrapper type.
+
 ## [0.8.2] - 2026-03-19
 
 ### Changed

Cargo.lock

@@ -26,6 +26,7 @@ serde_json = "1.0"
 tempfile = "3.0"
 http = "1.0"
 url = "2.5.4"
+percent-encoding = "2.3"
 whoami = "2.0"
 syn = "2.0"
 quote = "1.0"

Cargo.toml

@@ -30,6 +30,7 @@ miette.workspace = true
 serde_json.workspace = true
 tempfile.workspace = true
 url.workspace = true
+percent-encoding.workspace = true
 whoami = { workspace = true, optional = true }
 linkme.workspace = true
 secrecy.workspace = true

secretspec/Cargo.toml

@@ -32,13 +32,12 @@
 //! secretspec check --provider awssm://production@us-east-1
 //! ```
 
-use super::Provider;
+use super::{Provider, ProviderUrl};
 use crate::{Result, SecretSpecError};
 use aws_sdk_secretsmanager::Client;
 use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
-use url::Url;
 
 /// Maximum number of secrets per BatchGetSecretValue API call.
 const AWS_BATCH_GET_MAX_SECRETS: usize = 20;
@@ -52,10 +51,10 @@ pub struct AwssmConfig {
     pub aws_profile: Option<String>,
 }
 
-impl TryFrom<&Url> for AwssmConfig {
+impl TryFrom<&ProviderUrl> for AwssmConfig {
     type Error = SecretSpecError;
 
-    fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
+    fn try_from(url: &ProviderUrl) -> std::result::Result<Self, Self::Error> {
         if url.scheme() != "awssm" {
             return Err(SecretSpecError::ProviderOperationFailed(format!(
                 "Invalid scheme '{}' for awssm provider. Expected 'awssm'.",
@@ -69,14 +68,11 @@ impl TryFrom<&Url> for AwssmConfig {
             if username.is_empty() {
                 None
             } else {
-                Some(username.to_string())
+                Some(username)
             }
         };
 
-        let region = url
-            .host_str()
-            .filter(|s| !s.is_empty())
-            .map(|s| s.to_string());
+        let region = url.host().filter(|s| !s.is_empty());
 
         Ok(Self {
             region,
@@ -85,14 +81,6 @@ impl TryFrom<&Url> for AwssmConfig {
     }
 }
 
-impl TryFrom<Url> for AwssmConfig {
-    type Error = SecretSpecError;
-
-    fn try_from(url: Url) -> std::result::Result<Self, Self::Error> {
-        (&url).try_into()
-    }
-}
-
 /// AWS Secrets Manager provider.
 ///
 /// This provider stores and retrieves secrets from AWS Secrets Manager using

secretspec/src/provider/awssm.rs

@@ -1,11 +1,10 @@
-use super::Provider;
+use super::{Provider, ProviderUrl};
 use crate::{Result, SecretSpecError};
 use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::fs;
 use std::path::PathBuf;
-use url::Url;
 
 /// Configuration for the dotenv provider.
 ///
@@ -43,7 +42,7 @@ impl Default for DotEnvConfig {
     }
 }
 
-impl TryFrom<&Url> for DotEnvConfig {
+impl TryFrom<&ProviderUrl> for DotEnvConfig {
     type Error = SecretSpecError;
 
     /// Creates a DotEnvConfig from a URL.
@@ -56,45 +55,24 @@ impl TryFrom<&Url> for DotEnvConfig {
     /// - `dotenv:///absolute/path` - Absolute path
     /// - `dotenv://.env` - Relative path (authority as filename)
     /// - `dotenv://` - Uses default `.env` in current directory
-    ///
-    /// # Examples
-    ///
-    /// ```ignore
-    /// use url::Url;
-    /// use secretspec::provider::dotenv::DotEnvConfig;
-    ///
-    /// let url = Url::parse("dotenv:///.env.production").unwrap();
-    /// let config: DotEnvConfig = (&url).try_into().unwrap();
-    /// assert_eq!(config.path.to_str().unwrap(), "/.env.production");
-    /// ```
-    fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
+    fn try_from(url: &ProviderUrl) -> std::result::Result<Self, Self::Error> {
         if url.scheme() != "dotenv" {
             return Err(SecretSpecError::ProviderOperationFailed(format!(
                 "Invalid scheme '{}' for dotenv provider",
                 url.scheme()
             )));
         }
 
-        // For dotenv URLs:
-        // - dotenv:///absolute/path -> url.path() = "/absolute/path"
-        // - dotenv://.env -> url.host_str() = ".env", url.path() = ""
-        // - dotenv:// -> url.host_str() = None, url.path() = ""
-
-        let path = if url.path() != "" && url.path() != "/" {
-            // Check if this is an absolute path (starts with /) or has a host
-            if let Some(host) = url.host_str() {
-                // Case like dotenv://config/.env.local -> host="config", path="/.env.local"
-                // We want "config/.env.local"
-                format!("{}{}", host, url.path())
+        let path_str = url.path();
+        let path = if path_str != "" && path_str != "/" {
+            if let Some(host) = url.host() {
+                format!("{}{}", host, path_str)
             } else {
-                // Absolute path from dotenv:///path
-                url.path().to_string()
+                path_str
             }
-        } else if let Some(host) = url.host_str() {
-            // Relative path from dotenv://filename
-            host.to_string()
+        } else if let Some(host) = url.host() {
+            host
         } else {
-            // Default case dotenv://
             ".env".to_string()
         };
 
@@ -169,13 +147,8 @@ impl Provider for DotEnvProvider {
         let path_str = self.config.path.display().to_string();
 
         if path_str == ".env" {
-            // Default case - just return "dotenv"
             "dotenv".to_string()
-        } else if path_str.starts_with('/') {
-            // Absolute path
-            format!("dotenv:{}", path_str)
         } else {
-            // Relative path
             format!("dotenv:{}", path_str)
         }
     }
@@ -309,28 +282,30 @@ mod tests {
 
     #[test]
     fn test_dotenv_url_parsing() {
+        use url::Url;
+
         // Test with absolute path using three slashes - this is the main syntax we want to support
-        let url = Url::parse("dotenv:///tmp/test/.env").unwrap();
+        let url = ProviderUrl::new(Url::parse("dotenv:///tmp/test/.env").unwrap());
         let config: DotEnvConfig = (&url).try_into().unwrap();
         assert_eq!(config.path.to_str().unwrap(), "/tmp/test/.env");
 
         // Test with relative path using two slashes - authority as filename
-        let url = Url::parse("dotenv://.env").unwrap();
+        let url = ProviderUrl::new(Url::parse("dotenv://.env").unwrap());
         let config: DotEnvConfig = (&url).try_into().unwrap();
         assert_eq!(config.path.to_str().unwrap(), ".env");
 
         // Test with relative path in subdirectory
-        let url = Url::parse("dotenv://config/.env.local").unwrap();
+        let url = ProviderUrl::new(Url::parse("dotenv://config/.env.local").unwrap());
         let config: DotEnvConfig = (&url).try_into().unwrap();
         assert_eq!(config.path.to_str().unwrap(), "config/.env.local");
 
         // Test with default (empty after //)
-        let url = Url::parse("dotenv://").unwrap();
+        let url = ProviderUrl::new(Url::parse("dotenv://").unwrap());
         let config: DotEnvConfig = (&url).try_into().unwrap();
         assert_eq!(config.path.to_str().unwrap(), ".env");
 
         // Test with relative path - host part becomes first part of path
-        let url = Url::parse("dotenv://foobar/custom/path/.env").unwrap();
+        let url = ProviderUrl::new(Url::parse("dotenv://foobar/custom/path/.env").unwrap());
         let config: DotEnvConfig = (&url).try_into().unwrap();
         assert_eq!(config.path.to_str().unwrap(), "foobar/custom/path/.env");
     }

secretspec/src/provider/dotenv.rs

@@ -1,9 +1,8 @@
-use super::Provider;
+use super::{Provider, ProviderUrl};
 use crate::{Result, SecretSpecError};
 use secrecy::SecretString;
 use serde::{Deserialize, Serialize};
 use std::env;
-use url::Url;
 
 /// Configuration for the environment variables provider.
 ///
@@ -20,7 +19,7 @@ use url::Url;
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct EnvConfig {}
 
-impl TryFrom<&Url> for EnvConfig {
+impl TryFrom<&ProviderUrl> for EnvConfig {
     type Error = SecretSpecError;
 
     /// Creates an `EnvConfig` from a URL.
@@ -37,7 +36,7 @@ impl TryFrom<&Url> for EnvConfig {
     /// let url = Url::parse("env://").unwrap();
     /// let config: EnvConfig = (&url).try_into().unwrap();
     /// ```
-    fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
+    fn try_from(url: &ProviderUrl) -> std::result::Result<Self, Self::Error> {
         if url.scheme() != "env" {
             return Err(SecretSpecError::ProviderOperationFailed(format!(
                 "Invalid scheme '{}' for env provider",

secretspec/src/provider/env.rs

@@ -30,13 +30,12 @@
 //! secretspec check --provider gcsm://my-gcp-project
 //! ```
 
-use super::Provider;
+use super::{Provider, ProviderUrl};
 use crate::{Result, SecretSpecError};
 use google_cloud_secretmanager_v1::client::SecretManagerService;
 use google_cloud_secretmanager_v1::model::{Replication, Secret, SecretPayload, replication};
 use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
-use url::Url;
 
 /// Configuration for the Google Cloud Secret Manager provider.
 ///
@@ -96,10 +95,10 @@ fn validate_gcp_project_id(project_id: &str) -> std::result::Result<(), SecretSp
     Ok(())
 }
 
-impl TryFrom<&Url> for GcsmConfig {
+impl TryFrom<&ProviderUrl> for GcsmConfig {
     type Error = SecretSpecError;
 
-    fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
+    fn try_from(url: &ProviderUrl) -> std::result::Result<Self, Self::Error> {
         if url.scheme() != "gcsm" {
             return Err(SecretSpecError::ProviderOperationFailed(format!(
                 "Invalid scheme '{}' for gcsm provider. Expected 'gcsm'.",
@@ -108,15 +107,11 @@ impl TryFrom<&Url> for GcsmConfig {
         }
 
         // Extract project ID from host portion: gcsm://project-id
-        let project_id = url
-            .host_str()
-            .filter(|s| !s.is_empty())
-            .ok_or_else(|| {
-                SecretSpecError::ProviderOperationFailed(
-                    "GCP project ID is required. Use format: gcsm://project-id".to_string(),
-                )
-            })?
-            .to_string();
+        let project_id = url.host().filter(|s| !s.is_empty()).ok_or_else(|| {
+            SecretSpecError::ProviderOperationFailed(
+                "GCP project ID is required. Use format: gcsm://project-id".to_string(),
+            )
+        })?;
 
         // Validate project ID format
         validate_gcp_project_id(&project_id)?;
@@ -125,14 +120,6 @@ impl TryFrom<&Url> for GcsmConfig {
     }
 }
 
-impl TryFrom<Url> for GcsmConfig {
-    type Error = SecretSpecError;
-
-    fn try_from(url: Url) -> std::result::Result<Self, Self::Error> {
-        (&url).try_into()
-    }
-}
-
 /// Google Cloud Secret Manager provider.
 ///
 /// This provider stores and retrieves secrets from Google Cloud Secret Manager using

secretspec/src/provider/gcsm.rs

@@ -1,9 +1,8 @@
-use super::Provider;
+use super::{Provider, ProviderUrl};
 use crate::{Result, SecretSpecError};
 use keyring::Entry;
 use secrecy::{ExposeSecret, SecretString};
 use serde::{Deserialize, Serialize};
-use url::Url;
 
 /// Configuration for the keyring provider.
 ///
@@ -18,23 +17,14 @@ pub struct KeyringConfig {
     pub folder_prefix: Option<String>,
 }
 
-impl TryFrom<&Url> for KeyringConfig {
+impl TryFrom<&ProviderUrl> for KeyringConfig {
     type Error = SecretSpecError;
 
     /// Creates a new KeyringConfig from a URL.
     ///
     /// The URL must have the scheme "keyring" (e.g., "keyring://" or
     /// "keyring://secretspec/shared/{profile}/{key}").
-    ///
-    /// # Examples
-    ///
-    /// ```ignore
-    /// # use url::Url;
-    /// # use secretspec::provider::keyring::KeyringConfig;
-    /// let url = Url::parse("keyring://").unwrap();
-    /// let config: KeyringConfig = (&url).try_into().unwrap();
-    /// ```
-    fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
+    fn try_from(url: &ProviderUrl) -> std::result::Result<Self, Self::Error> {
         if url.scheme() != "keyring" {
             return Err(SecretSpecError::ProviderOperationFailed(format!(
                 "Invalid scheme '{}' for keyring provider",
@@ -44,12 +34,9 @@ impl TryFrom<&Url> for KeyringConfig {
 
         let mut config = Self::default();
 
-        if let Some(host) = url.host_str() {
+        if let Some(host) = url.host() {
             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);
+            config.folder_prefix = Some(format!("{}{}", host, path));
         }
 
         Ok(config)
@@ -121,7 +108,7 @@ impl Provider for KeyringProvider {
 
     fn uri(&self) -> String {
         if let Some(ref prefix) = self.config.folder_prefix {
-            format!("keyring://{}", prefix)
+            format!("keyring://{}", ProviderUrl::encode(prefix))
         } else {
             "keyring".to_string()
         }