feat: add per-secret provider configuration with fallback chains

[domenkozar]

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

[claude]

Claude finished @domenkozar's task —— View job

---

PR Review Complete ✅

This pull request adds per-secret provider configuration with fallback chains - a well-implemented feature with excellent test coverage.

Todo List

• Read and analyze changed files
• Review core provider resolution logic
• Examine CLI command implementations
• Check test coverage and quality
• Provide comprehensive feedback

Code Quality Analysis

Core Implementation (secrets.rs)

Strengths:

• Well-structured provider fallback logic in get_secret_from_providers (lines 393-417)
• Clear separation between alias resolution and provider instantiation
• Proper error handling with informative messages
• Good encapsulation with proper visibility modifiers

Potential Issues:

• Performance: resolve_provider_aliases creates new provider instances for each operation in validation. Consider caching provider instances.
• Memory: Multiple URI resolution could be optimized - currently resolves aliases repeatedly in various methods.

Configuration (config.rs)

Strengths:

• Clean addition of providers field to Secret struct (line 342)
• Proper serde annotations for optional fields
• Good integration with existing inheritance logic

CLI Implementation (cli/mod.rs)

Strengths:

• Comprehensive provider alias management commands (lines 114-129)
• Good user feedback with colored output
• Proper error handling and validation

Minor Issues:

• Lines 408-417 could benefit from extracting the provider insertion logic into a helper method

Test Coverage

Excellent Coverage:

• test_per_secret_provider_configuration - Tests basic per-secret provider setup
• test_provider_alias_resolution - Tests alias to URI mapping
• test_provider_alias_not_found - Tests error cases
• test_per_secret_provider_with_fallback_chain - Tests fallback ordering
• test_get_secret_with_fallback_chain - Integration test for fallback behavior
• test_validate_with_per_secret_providers - Tests validation with mixed providers

Security Analysis

Good Security Practices:

• No hardcoded secrets or sensitive data
• Proper use of SecretString for handling sensitive values
• Provider URIs are properly validated through existing provider system

Performance Considerations

Areas for Optimization:

• Provider alias resolution happens multiple times - could cache resolved URIs
• get_secret_from_providers creates new provider instances on each call - consider provider pooling

Architecture & Design

Strengths:

• Maintains backward compatibility
• Clean separation of concerns
• Follows existing patterns in the codebase
• Provider aliases keep sensitive provider details out of project configs

Design Decisions:

• Choice to resolve aliases in Secrets rather than Config is appropriate
• Fallback chain approach is intuitive and well-implemented

Issues Found

1. Missing Provider Validation in set() method

In secrets.rs:485-500, when setting secrets with per-secret providers, only the first provider is used. Consider validating all providers in the chain exist:

// Current: Only uses first provider
let backend = if let Some(provider_aliases) = secret_config
    .as_ref()
    .and_then(|sc| sc.providers.as_ref())
    .and_then(|p| p.first())

2. Provider Resolution Error Messages

Error messages in resolve_provider_aliases (lines 307-327) could be more specific about which operation failed.

3. Memory Allocation

Multiple Vec allocations in resolve_provider_aliases could be optimized with pre-allocation when size is known.

Minor Suggestions

1. Extract Helper Methods: The provider resolution logic could be extracted into smaller, testable methods
2. Documentation: Consider adding more examples in docstrings for the new per-secret provider syntax
3. Validation: Add validation that provider aliases don't contain circular references

Overall Assessment

This is a high-quality implementation that:

• ✅ Adds significant value with fallback chain functionality
• ✅ Maintains excellent backward compatibility
• ✅ Has comprehensive test coverage (8+ new tests)
• ✅ Follows existing code patterns and conventions
• ✅ Includes proper CLI integration
• ✅ Has good error handling and user feedback

The implementation is production-ready with only minor optimization opportunities.

Recommendation: Approve - This PR is well-designed, thoroughly tested, and ready for production use.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	secretspec	da10512	Commit Preview URL Branch Preview URL	Nov 04 2025, 05:47 PM

[claude]

Claude finished @domenkozar's task —— View job

---

PR Review Complete ✅

Todo List

• Read and analyze changed files
• Review core provider resolution logic
• Examine CLI command implementations
• Check test coverage and quality
• Provide comprehensive feedback

Code Quality Analysis

Core Implementation (secrets.rs)

Strengths:

• Well-structured provider fallback logic in get_secret_from_providers (lines 393-417)
• Clear separation between alias resolution and provider instantiation
• Proper error handling with informative messages
• Good encapsulation with proper visibility modifiers

Potential Issues:

• Performance: resolve_provider_aliases creates new provider instances for each operation in validation. Consider caching provider instances.
• Memory: Multiple URI resolution could be optimized - currently resolves aliases repeatedly in various methods.

Configuration (config.rs)

Strengths:

• Clean addition of providers field to Secret struct (line 342)
• Proper serde annotations for optional fields
• Good integration with existing inheritance logic

CLI Implementation (cli/mod.rs)

Strengths:

• Comprehensive provider alias management commands (lines 114-129)
• Good user feedback with colored output
• Proper error handling and validation

Minor Issues:

• Lines 408-417 could benefit from extracting the provider insertion logic into a helper method

Test Coverage

Excellent Coverage:

• test_per_secret_provider_configuration - Tests basic per-secret provider setup
• test_provider_alias_resolution - Tests alias to URI mapping
• test_provider_alias_not_found - Tests error cases
• test_per_secret_provider_with_fallback_chain - Tests fallback ordering
• test_get_secret_with_fallback_chain - Integration test for fallback behavior
• test_validate_with_per_secret_providers - Tests validation with mixed providers

Security Analysis

Good Security Practices:

• No hardcoded secrets or sensitive data
• Proper use of SecretString for handling sensitive values
• Provider URIs are properly validated through existing provider system

Performance Considerations

Areas for Optimization:

• Provider alias resolution happens multiple times - could cache resolved URIs
• get_secret_from_providers creates new provider instances on each call - consider provider pooling

Architecture & Design

Strengths:

• Maintains backward compatibility
• Clean separation of concerns
• Follows existing patterns in the codebase
• Provider aliases keep sensitive provider details out of project configs

Design Decisions:

• Choice to resolve aliases in Secrets rather than Config is appropriate
• Fallback chain approach is intuitive and well-implemented

Issues Found

1. Missing Provider Validation in set() method

In secrets.rs:485-500, when setting secrets with per-secret providers, only the first provider is used. Consider validating all providers in the chain exist:

// Current: Only uses first provider
let backend = if let Some(provider_aliases) = secret_config
    .as_ref()
    .and_then(|sc| sc.providers.as_ref())
    .and_then(|p| p.first())

2. Provider Resolution Error Messages

Error messages in resolve_provider_aliases (lines 307-327) could be more specific about which operation failed.

3. Memory Allocation

Multiple Vec allocations in resolve_provider_aliases could be optimized with pre-allocation when size is known.

Minor Suggestions

1. Extract Helper Methods: The provider resolution logic could be extracted into smaller, testable methods
2. Documentation: Consider adding more examples in docstrings for the new per-secret provider syntax
3. Validation: Add validation that provider aliases don't contain circular references

Overall Assessment

This is a high-quality implementation that:

• ✅ Adds significant value with fallback chain functionality
• ✅ Maintains excellent backward compatibility
• ✅ Has comprehensive test coverage (8+ new tests)
• ✅ Follows existing code patterns and conventions
• ✅ Includes proper CLI integration
• ✅ Has good error handling and user feedback

The implementation is production-ready with only minor optimization opportunities.

Recommendation: Approve - This PR is well-designed, thoroughly tested, and ready for production use.