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	f8914ca	Commit Preview URL Branch Preview URL	Nov 21 2025, 06:26 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.

[claude]

Claude finished @domenkozar's task —— View job

---

PR Review Complete ✅

Todo List

• Read and analyze core implementation files
• Review CLI command implementations
• Examine configuration changes
• Check test coverage and quality
• Assess security and performance implications
• Provide comprehensive code review feedback

Code Quality Analysis

Core Implementation (secrets.rs)

Strengths:

• Well-structured fallback logic: The get_secret_from_providers method (lines 423-447) implements a clean fallback chain pattern that tries providers in order until one succeeds
• Clear provider resolution: The resolve_provider_aliases method (lines 323-364) properly converts aliases to URIs with comprehensive error handling
• Proper error messages: Detailed error messages that include available aliases when provider resolution fails (lines 337-345)
• Good separation of concerns: Provider instantiation is properly separated from alias resolution

Potential Issues:

• Performance concern: resolve_provider_aliases creates new URI strings each time - consider caching resolved URIs for frequently accessed secrets
• Memory usage: Multiple Vec allocations in provider resolution could be optimized with pre-sized vectors when the alias count is known
• Provider instance creation: get_secret_from_providers creates new provider instances on each call (line 434) - provider pooling could improve performance for frequently accessed secrets

Configuration (config.rs)

Strengths:

• Clean data structure: The providers field addition to the Secret struct (line 370) is well-integrated with existing serde annotations
• Proper field documentation: Clear documentation explaining the fallback behavior (lines 364-371)
• Consistent with existing patterns: The optional field pattern matches other secret configuration fields

CLI Implementation (cli/mod.rs)

Strengths:

• Comprehensive provider alias management: Commands for add/remove/list operations with proper error handling (lines 397-480)
• Good user feedback: Clear success/error messages with colored output
• Robust config handling: Creates config file if it doesn't exist, initializes providers map as needed

Minor Issues:

• Code duplication: Provider insertion logic (lines 418-427) could benefit from extraction into a helper method
• Error consistency: Some error messages use different formatting styles

Test Coverage

Excellent Coverage - 8+ New Tests:

• test_per_secret_provider_configuration (line 2321) - Tests basic per-secret provider setup
• test_provider_alias_resolution (line 2393) - Tests alias to URI mapping
• test_provider_alias_not_found (line 2461) - Tests error cases
• test_per_secret_provider_with_fallback_chain (line 2499) - Tests fallback ordering
• test_get_secret_with_fallback_chain (line 2592) - Integration test for fallback behavior
• test_validate_with_per_secret_providers (line 2685) - Tests validation with mixed providers
• test_secret_config_merges_providers_from_default (line 2811) - Tests inheritance
• test_cli_provider_alias_operations (line 2992) - Tests CLI commands

The test coverage is comprehensive and covers both happy path and error scenarios.

Security Analysis

Good Security Practices:

• No hardcoded secrets: All sensitive data properly handled through SecretString
• Proper URI validation: Provider URIs validated through existing provider system
• No credential exposure: Provider aliases keep sensitive URIs out of project configs

Security Considerations:

• Provider URIs in global config could contain sensitive connection details - this is by design and properly isolated from project configs

Performance Analysis

Areas for Optimization:

1. Provider Alias Resolution Caching: The resolve_provider_aliases method could cache results to avoid repeated URI resolution
2. Provider Instance Pooling: Creating new provider instances for each secret access could be expensive - consider caching provider instances
3. Memory Allocations: Multiple Vec and String allocations in provider resolution could be optimized

Estimated Impact: Low-medium - these optimizations would mainly help with high-frequency secret access patterns

Architecture & Design

Strengths:

• Backward compatibility: All existing configurations work without changes
• Intuitive fallback chain design: The ordered provider list pattern is easy to understand
• Clean separation: Provider alias management is properly separated from core secret logic
• Flexible provider resolution: Supports both per-secret and global provider configuration

Design Decisions:

• Alias resolution in Secrets vs Config: The choice to resolve aliases in the Secrets struct is appropriate as it has access to global config
• First provider for write operations: Using only the first provider for set() operations (line 518) is a reasonable design choice that prevents data inconsistency

Issues Found

1. Limited Provider Validation in set() Method

Location: secrets.rs:515-530

The set() method only uses the first provider from the fallback chain. While this prevents data inconsistency, it could benefit from validating that all providers in the chain exist before attempting to write:

// 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())

Recommendation: Consider adding validation that all provider aliases resolve before writing.

2. Error Context in Provider Resolution

Location: secrets.rs:337-358

Error messages could be more specific about which operation failed (get vs set vs validate).

3. Memory Optimization Opportunity

Location: secrets.rs:328

The Vec::new() allocation could be pre-sized when the alias count is known.

Minor Suggestions

1. Extract Helper Methods: Provider resolution logic could be broken down into smaller, more testable methods
2. Provider Instance Caching: Consider caching provider instances for better performance
3. Documentation: Add more examples in docstrings showing per-secret provider syntax

Overall Assessment

This is a high-quality implementation that:

• ✅ Adds significant value with comprehensive fallback chain functionality
• ✅ Maintains excellent backward compatibility
• ✅ Has exceptional test coverage (8+ comprehensive tests)
• ✅ Follows existing code patterns and conventions perfectly
• ✅ Includes robust CLI integration with alias management
• ✅ Provides excellent error handling and user feedback
• ✅ Uses secure coding practices throughout

The implementation is production-ready with only minor optimization opportunities. The fallback chain pattern is well-designed and the alias system elegantly solves the provider URI management problem.

Recommendation: Approve - This PR represents high-quality work that significantly enhances the project's functionality while maintaining code quality standards.