feat: add per-secret provider configuration with fallback chains

Add support for configuring different providers for individual secrets,
enabling fallback chains where secrets can be retrieved from multiple
providers in order of preference.

New features:
- Per-secret `providers` field in configuration (list of provider aliases)
- Provider alias management in global config (~/.config/secretspec/config.toml)
- CLI commands to manage aliases: config provider add/remove/list
- Fallback chain resolution for secure multi-provider setups

This allows complex scenarios like:
- Try OnePassword vault first, fall back to keyring
- Different providers for different environments
- Shared vs environment-specific provider locations

Implementation includes:
- New resolve_provider_aliases() method for alias → URI conversion
- New get_secret_from_providers() for fallback chain resolution
- Updated all secret operations (get, set, validate, import, run)
- CLI provider alias management commands
- Comprehensive unit and integration tests:
  * test_per_secret_provider_configuration
  * test_provider_alias_resolution
  * test_provider_alias_not_found
  * test_per_secret_provider_with_fallback_chain
  * test_get_secret_with_fallback_chain (new integration test)
  * test_validate_with_per_secret_providers (new integration test)
  * test_secret_config_merges_providers_from_default (new integration test)
  * test_cli_provider_alias_operations (new integration test)

All tests pass (63 tests in secretspec, 19 in secretspec-derive).

Fixes #10

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: domenkozar

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Per-secret provider configuration: secrets can now specify their own provider(s) with fallback chains
+- New `providers` field in secret configuration (list of provider aliases tried in order)
+- Provider alias management via `secretspec config provider add/remove/list` commands
+- New `providers` map in global config for defining named provider aliases
+
+### Changed
+- Secret configuration now supports `providers: [...]` field instead of single provider assignment
+- Provider resolution includes per-secret provider overrides before falling back to global defaults
+
 ## [0.3.3] - 2025-09-10
 
 ### Fixed

CLAUDE.md

@@ -66,10 +66,46 @@ Providers support URI-based configuration (e.g., `keyring://`, `onepassword://va
 4. Falls back to "default" profile
 
 ### Provider Resolution
-1. CLI flag (`--provider`)
-2. Environment variable (`SECRETSPEC_PROVIDER`)
-3. User config default per profile
-4. Falls back to keyring provider
+1. **Per-secret providers** (with fallback chain): specified in `secretspec.toml` as `providers: [alias1, alias2, ...]`
+   - Aliases resolved against `~/.config/secretspec/config.toml` providers map
+   - Tries each provider in order until secret is found
+2. CLI flag (`--provider`)
+3. Environment variable (`SECRETSPEC_PROVIDER`)
+4. User config default provider
+5. Falls back to keyring provider
+
+### Per-Secret Provider Configuration
+Secrets can specify their own providers using the `providers` field to override global defaults:
+
+```toml
+[profiles.production]
+DATABASE_URL = { description = "Production DB", providers = ["prod_vault", "keyring"] }
+API_KEY = { description = "API Key", providers = ["shared"] }
+GITHUB_TOKEN = { description = "GitHub token from env", providers = ["env"] }
+```
+
+Provider aliases are defined in `~/.config/secretspec/config.toml`:
+```toml
+[defaults]
+provider = "keyring"
+
+[providers]
+prod_vault = "onepassword://vault/Production"
+shared = "onepassword://vault/Shared"
+env = "env://"
+```
+
+Or managed via CLI:
+```bash
+# Add provider alias
+secretspec config provider add prod_vault "onepassword://vault/Production"
+
+# List all aliases
+secretspec config provider list
+
+# Remove alias
+secretspec config provider remove prod_vault
+```
 
 ### Secret Resolution
 1. Check active profile for secret

docs/src/content/docs/concepts/providers.md

@@ -19,9 +19,10 @@ Providers are pluggable storage backends that handle the storage and retrieval o
 
 SecretSpec determines which provider to use in this order:
 
-1. **CLI flag**: `secretspec --provider` flag
-2. **Environment**: `SECRETSPEC_PROVIDER` (highest priority)
-3. **Global default**: Default provider in user config set via `secretspec config init`
+1. **Per-secret providers**: `providers` field in `secretspec.toml` (highest priority, with fallback chain)
+2. **CLI flag**: `secretspec --provider` flag
+3. **Environment**: `SECRETSPEC_PROVIDER`
+4. **Global default**: Default provider in user config set via `secretspec config init`
 
 ## Configuration
 
@@ -61,6 +62,59 @@ $ secretspec run --provider "onepassword://Personal/Development" -- npm start
 $ secretspec run --provider "dotenv:/home/user/work/.env" -- npm test
 ```
 
+## Per-Secret Provider Configuration
+
+For fine-grained control, you can specify different providers for individual secrets using the `providers` field in `secretspec.toml`. This enables fallback chains where secrets are retrieved from multiple providers in order of preference:
+
+```toml
+[profiles.production]
+DATABASE_URL = { description = "Production DB", providers = ["prod_vault", "keyring"] }
+API_KEY = { description = "API key from env", providers = ["env"] }
+SENTRY_DSN = { description = "Error tracking", providers = ["shared_vault", "keyring"] }
+```
+
+Provider aliases are defined in your user configuration file (`~/.config/secretspec/config.toml`):
+
+```toml
+[defaults]
+provider = "keyring"
+
+[providers]
+prod_vault = "onepassword://vault/Production"
+shared_vault = "onepassword://vault/Shared"
+env = "env://"
+```
+
+### Fallback Chains
+
+When a secret specifies multiple providers, SecretSpec tries each provider in order until it finds the secret:
+
+```toml
+# Try OnePassword first, then fall back to keyring if not found
+DATABASE_URL = { description = "DB", providers = ["prod_vault", "keyring"] }
+```
+
+This enables complex workflows:
+- **Shared vs environment-specific**: Try a shared vault first, fall back to local keyring
+- **Redundancy**: Maintain secrets in multiple locations for backup
+- **Migration**: Gradually move secrets from one provider to another
+- **Multi-team setups**: Different teams can manage different providers
+
+### Managing Provider Aliases
+
+Use CLI commands to manage provider aliases:
+
+```bash
+# Add a provider alias
+$ secretspec config provider add prod_vault "onepassword://vault/Production"
+
+# List all aliases
+$ secretspec config provider list
+
+# Remove an alias
+$ secretspec config provider remove prod_vault
+```
+
 ## Next Steps
 
 - Learn about specific providers in the [Providers](/providers/keyring/) section

docs/src/content/docs/reference/cli.md

@@ -54,6 +54,57 @@ Provider: keyring
 Profile:  development
 ```
 
+### config provider add
+Add a provider alias to your configuration.
+
+```bash
+secretspec config provider add <ALIAS> <URI>
+```
+
+**Arguments:**
+- `<ALIAS>` - Short name for the provider (e.g., `prod_vault`, `shared`)
+- `<URI>` - Provider URI (e.g., `onepassword://vault/Production`, `env://`)
+
+**Example:**
+```bash
+$ secretspec config provider add prod_vault "onepassword://vault/Production"
+✓ Provider alias 'prod_vault' saved
+
+$ secretspec config provider add shared "onepassword://vault/Shared"
+✓ Provider alias 'shared' saved
+```
+
+### config provider list
+List all configured provider aliases.
+
+```bash
+secretspec config provider list
+```
+
+**Example:**
+```bash
+$ secretspec config provider list
+prod_vault  → onepassword://vault/Production
+shared      → onepassword://vault/Shared
+env         → env://
+```
+
+### config provider remove
+Remove a provider alias from your configuration.
+
+```bash
+secretspec config provider remove <ALIAS>
+```
+
+**Arguments:**
+- `<ALIAS>` - Name of the alias to remove
+
+**Example:**
+```bash
+$ secretspec config provider remove prod_vault
+✓ Provider alias 'prod_vault' removed
+```
+
 ### check
 Check if all required secrets are available, with interactive prompting for missing secrets.
 

docs/src/content/docs/reference/configuration.md

@@ -45,8 +45,9 @@ Each secret variable is defined as a table with the following fields:
 | `description` | string | Yes | Human-readable description of the secret |
 | `required` | boolean | No* | Whether the value must be provided (default: true) |
 | `default` | string | No** | Default value if not provided |
+| `providers` | array[string] | No | List of provider aliases to use in fallback order |
 
-*If `default` is provided, `required` defaults to false  
+*If `default` is provided, `required` defaults to false
 **Only valid when `required = false`
 
 ## Complete Example
@@ -62,6 +63,7 @@ extends = ["../shared/secretspec.toml"]  # Optional inheritance
 [profiles.default]
 APP_NAME = { description = "Application name", required = false, default = "MyApp" }
 LOG_LEVEL = { description = "Log verbosity", required = false, default = "info" }
+GITHUB_TOKEN = { description = "GitHub token", required = true, providers = ["env"] }
 
 # Development profile - extends default
 [profiles.development]
@@ -71,12 +73,39 @@ DEBUG = { description = "Debug mode", required = false, default = "true" }
 
 # Production profile - extends default
 [profiles.production]
-DATABASE_URL = { description = "PostgreSQL cluster connection", required = true }
+DATABASE_URL = { description = "PostgreSQL cluster connection", required = true, providers = ["prod_vault", "keyring"] }
 API_URL = { description = "Production API endpoint", required = true }
-SENTRY_DSN = { description = "Error tracking service", required = true }
+SENTRY_DSN = { description = "Error tracking service", required = true, providers = ["shared_vault"] }
 REDIS_URL = { description = "Redis cache connection", required = true }
 ```
 
+### Provider Aliases
+
+When using per-secret provider configuration, provider aliases must be defined in your user configuration file at `~/.config/secretspec/config.toml`:
+
+```toml
+[defaults]
+provider = "keyring"
+
+[providers]
+prod_vault = "onepassword://vault/Production"
+shared_vault = "onepassword://vault/Shared"
+env = "env://"
+```
+
+Manage provider aliases using CLI commands:
+
+```bash
+# Add a provider alias
+$ secretspec config provider add prod_vault "onepassword://vault/Production"
+
+# List all aliases
+$ secretspec config provider list
+
+# Remove an alias
+$ secretspec config provider remove prod_vault
+```
+
 ## Profile Inheritance
 
 - All profiles automatically inherit from `[profiles.default]`