secvault 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 243d63e08d1e0efc90840322ebe46d547a6733829e4cde6f009dcaee457fb141
-  data.tar.gz: 0c927adb97f3fdfa9e4680d59825b50b2741b11cb8131c1e61b0eca42dec75fb
+  metadata.gz: 18d7c81d380aa63a8092f4bd91a438ee3e02282695b6fcbe6841ffbb81a30a9b
+  data.tar.gz: 2dbe018b171e0840e9a6047027fcf8e60ef73ec60867e4f6f4f97240df74f126
 SHA512:
-  metadata.gz: 0abb15b103100f8205b1ec4c7890d51b9ad8d8c0f55d8d96e1f55b0e85b6d0ade146c382c32e187bfb2c952d02a3fc940ee33b9c6f9beabe598b7773e9cf9fa9
-  data.tar.gz: 12edf2aad07063edb1d4385bedcc8899d388eefef26499671cdddf2bc37c67bfeec39fc08729e09e19c63c04021f28642276f81354b1729a7e08940b5a47fcc9
+  metadata.gz: c864336bbb71f184bf09e9f3bc0c191cbd7f7d750ee5a9c541cc3711b0ddc0cc608103e574dffd940b64dc814b4d5b5f433940ef0adf6235e3d17caf9f5784ce
+  data.tar.gz: 6c62bb91d5a9a0ca1ac0a984f94c92d11c9815d8832e371b7b362d2d6142e1a5f6ea5b058ce8d7762708c271c4cfe848b753d8ea2c6c1dbf47ace950c6df16fd

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [2.3.0] - 2025-09-22
+
+### Changed
+
+- **Better method naming**: Renamed `setup_rails_71_integration!` to `setup_backward_compatibility_with_older_rails!`
+- **More generic approach**: New method name works for any older Rails version, not just 7.1
+- **Updated documentation**: README now uses "Older Rails Integration" instead of "Rails 7.1 Integration"
+- **Clearer version support**: Documentation now shows "Rails 7.1 and older" for better clarity
+
+### Backward Compatibility
+
+- ✅ **Old method name still works**: `setup_rails_71_integration!` is aliased to the new method
+- ✅ **No breaking changes**: All existing code continues to work
+- ✅ **Updated test apps**: Rails 7.1 test app uses the new, cleaner method name
+
+### Benefits
+
+- **Future-proof naming**: Works for Rails 7.1, 7.0, 6.x, or any version with native secrets
+- **Clearer intent**: Method name clearly indicates it's for backward compatibility
+- **Better documentation**: More generic approach in README and code comments
+- **Maintained compatibility**: Existing users don't need to change anything
+
 ## [2.2.0] - 2025-09-22
 
 ### Added

data/README.md

@@ -1,12 +1,22 @@
 # Secvault
 
-Restores the classic Rails `secrets.yml` functionality that was removed in Rails 7.2. Uses simple, plain YAML files for environment-specific secrets management.
+Restores the classic Rails `secrets.yml` functionality that was removed in Rails 7.2. Uses simple, plain YAML files for environment-specific secrets management with powerful features like YAML defaults, ERB interpolation, and multi-file configurations.
 
 **Rails Version Support:**
-- **Rails 7.1**: Manual setup (see Rails 7.1 Integration below)
+- **Rails 7.1 and older**: Manual setup (see Older Rails Integration below)
 - **Rails 7.2+**: Automatic setup
 - **Rails 8.0+**: Full compatibility
 
+## ✨ Key Features
+
+- 🔗 **YAML Anchor/Alias Support**: Use `default: &default` for shared configuration
+- 🌍 **ERB Interpolation**: Environment variables with type conversion (`ENV['VAR'].to_i`, boolean logic)
+- 📁 **Multi-File Loading**: Merge multiple YAML files (e.g., base + OAuth + local overrides)
+- 🔄 **Environment Switching**: Load different environments dynamically
+- 🛠️ **Development Tools**: Hot-reload secrets without server restart
+- 🔍 **Utility Methods**: `Secvault.active?` to check integration status
+- 🏗️ **Flexible Organization**: Feature-based, environment-based, or namespace-based file structures
+
 ## Installation
 
 ```ruby
@@ -34,32 +44,91 @@ Rails.application.secrets.api_key
 Rails.application.secrets.database_password
 ```
 
-**Example secrets.yml:**
+**Example secrets.yml with YAML defaults and ERB:**
 ```yaml
+# YAML defaults - inherited by all environments
+default: &default
+  app_name: "My Application"
+  database:
+    adapter: "postgresql"
+    pool: 5
+    timeout: 5000
+  api:
+    timeout: 30
+    retries: 3
+
 development:
-  api_key: dev_key
-  database_password: dev_password
+  <<: *default  # Inherit defaults
+  api_key: "dev_api_key_123"
+  database:
+    host: "localhost"
+    name: "myapp_development"
+  api:
+    base_url: "http://localhost:3000"  # Override default
 
 production:
+  <<: *default  # Inherit defaults
   api_key: <%= ENV['API_KEY'] %>
-  database_password: <%= ENV['DATABASE_PASSWORD'] %>
+  database:
+    host: <%= ENV['DATABASE_HOST'] %>
+    name: <%= ENV['DATABASE_NAME'] %>
+    pool: <%= ENV.fetch('DATABASE_POOL', '10').to_i %>  # Type conversion
+  api:
+    base_url: <%= ENV['API_BASE_URL'] %>
+  
+  # Boolean conversion
+  features:
+    new_ui: <%= ENV.fetch('FEATURE_NEW_UI', 'true') == 'true' %>
+  
+  # Array conversion
+  oauth_scopes: <%= ENV.fetch('OAUTH_SCOPES', 'email,profile').split(',') %>
 ```
 
-**Production:** Use environment variables in your YAML:
-```yaml
-production:
-  api_key: <%= ENV['API_KEY'] %>
+## Multi-File Configuration
+
+Organize secrets across multiple files for better maintainability:
+
+```ruby
+# config/initializers/secvault.rb
+require "secvault"
+Secvault.setup_backward_compatibility_with_older_rails!
+
+Rails.application.config.after_initialize do
+  # Load multiple files in order (later files override earlier ones)
+  secrets_files = [
+    Rails.root.join('config', 'secrets.yml'),         # Base secrets
+    Rails.root.join('config', 'secrets.oauth.yml'),   # OAuth & APIs
+    Rails.root.join('config', 'secrets.local.yml')    # Local overrides
+  ]
+  
+  existing_files = secrets_files.select(&:exist?)
+  
+  if existing_files.any?
+    merged_secrets = Rails::Secrets.parse(existing_files, env: Rails.env)
+    secrets_object = ActiveSupport::OrderedOptions.new
+    secrets_object.merge!(merged_secrets)
+    Rails.application.define_singleton_method(:secrets) { secrets_object }
+  end
+end
+```
+
+**File organization example:**
+```
+config/
+├── secrets.yml           # Base application secrets
+├── secrets.oauth.yml     # OAuth providers & external APIs
+├── secrets.local.yml     # Local development overrides (gitignored)
 ```
 
 ## Advanced Usage
 
-**Multiple secrets files (merged in order):**
+**Manual multi-file parsing:**
 ```ruby
 # Parse multiple files - later files override earlier ones
 secrets = Rails::Secrets.parse([
   'config/secrets.yml',
-  'config/secrets.local.yml',
-  'config/secrets.production.yml'
+  'config/secrets.oauth.yml',
+  'config/secrets.local.yml'
 ], env: Rails.env)
 ```
 
@@ -72,25 +141,58 @@ production_secrets = Rails::Secrets.load(env: 'production')
 dev_secrets = Rails::Secrets.load(env: 'development')
 ```
 
-**Custom files:**
+**Environment-specific loading:**
 ```ruby
-# Parse a custom secrets file
-custom_secrets = Rails::Secrets.parse(['config/custom.yml'], env: Rails.env)
+# Load production secrets in any environment
+production_secrets = Rails::Secrets.load(env: 'production')
 
-# Parse from different paths
-all_secrets = Rails::Secrets.parse([
-  Rails.root.join('config', 'secrets.yml'),
-  Rails.root.join('config', 'deploy', 'secrets.yml')
-], env: Rails.env)
+# Load development secrets
+dev_secrets = Rails::Secrets.load(env: 'development')
 ```
 
-## Rails 7.1 Integration
+## ERB Features & Type Conversion
 
-Test Secvault in Rails 7.1 before upgrading to 7.2+:
+Secvault supports powerful ERB templating with automatic type conversion:
+
+```yaml
+production:
+  # String interpolation
+  api_key: <%= ENV['API_KEY'] %>
+  
+  # Integer conversion
+  database_pool: <%= ENV.fetch('DB_POOL', '10').to_i %>
+  
+  # Boolean conversion  
+  debug_enabled: <%= ENV.fetch('DEBUG', 'false') == 'true' %>
+  
+  # Array conversion
+  allowed_hosts: <%= ENV.fetch('HOSTS', 'localhost,127.0.0.1').split(',') %>
+  
+  # Fallback values
+  timeout: <%= ENV.fetch('TIMEOUT', '30').to_i %>
+  adapter: <%= ENV.fetch('DB_ADAPTER', 'postgresql') %>
+```
+
+## Development Tools
+
+**Hot-reload secrets (development only):**
+```ruby
+# In Rails console or code
+reload_secrets!  # Reloads all secrets files without server restart
+```
+
+**Check integration status:**
+```ruby
+Secvault.active?  # Returns true if Secvault is managing secrets
+```
+
+## Older Rails Integration
+
+For Rails versions with existing secrets functionality (like Rails 7.1), use Secvault to test before upgrading:
 
 ```ruby
 # config/initializers/secvault.rb
-Secvault.setup_rails_71_integration!
+Secvault.setup_backward_compatibility_with_older_rails!
 ```
 
 This replaces Rails.application.secrets with Secvault functionality. Your existing Rails 7.1 code works unchanged:
@@ -102,12 +204,68 @@ Rails::Secrets.load                        # ✅ Load default config/secrets.yml
 Rails::Secrets.parse(['custom.yml'], env: Rails.env)  # ✅ Parse custom files
 ```
 
+**Check if Secvault is active:**
+```ruby
+if Secvault.active?
+  puts "Using Secvault for secrets management"
+else
+  puts "Using default Rails secrets functionality"
+end
+```
+
+## Usage Examples
+
+**Basic usage:**
+```ruby
+# Access secrets
+Rails.application.secrets.api_key
+Rails.application.secrets.database.host
+Rails.application.secrets.oauth.google.client_id
+
+# With YAML defaults, you get deep merging:
+Rails.application.secrets.database.adapter  # "postgresql" (from default)
+Rails.application.secrets.database.host     # "localhost" (from environment)
+```
+
+**Multi-file merging:**
+```ruby
+# Files loaded in order: base → oauth → local
+# Later files override earlier ones for the same keys
+# Hash values are deep merged, scalars are replaced
+
+Rails.application.secrets.api_key           # Could be from base or local file
+Rails.application.secrets.oauth.google      # From oauth file
+Rails.application.secrets.features.debug   # From local file override
+```
+
+## Security Best Practices
+
+### ⚠️ Production Security
+- **Never commit production secrets** to version control
+- **Use environment variables** in production with ERB: `<%= ENV['SECRET'] %>`
+- **Use ENV.fetch()** with fallbacks: `<%= ENV.fetch('SECRET', 'default') %>`
 
-## Security
+### 📝 File Management
+- **Add sensitive files** to `.gitignore`:
+  ```gitignore
+  config/secrets.yml         # If contains sensitive data
+  config/secrets.local.yml   # Local development overrides
+  config/secrets.production.yml  # If used
+  ```
 
-⚠️ Never commit production secrets to version control  
-✅ Use environment variables for production secrets with ERB syntax: `<%= ENV['SECRET'] %>`  
-✅ Add `config/secrets.yml` to `.gitignore` if it contains sensitive data
+### 🔑 Recommended Structure
+```yaml
+# ✅ GOOD: Base file with safe defaults
+development:
+  api_key: "safe_dev_key_for_team"
+  
+production:
+  api_key: <%= ENV['API_KEY'] %>  # ✅ From environment
+
+# ❌ BAD: Secrets hardcoded in base file
+production:
+  api_key: "super_secret_production_key"  # ❌ Never do this
+```
 
 ## License
 

data/lib/secvault/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Secvault
-  VERSION = "2.2.0"
+  VERSION = "2.4.0"
 end

data/lib/secvault.rb

@@ -58,6 +58,11 @@ module Secvault
 
   extend self
 
+  # Check if Secvault is currently active in the Rails application
+  def active?
+    defined?(Rails) && Rails::Secrets == Secvault::RailsSecrets
+  end
+
   def install!
     return if defined?(Rails::Railtie).nil?
 
@@ -65,18 +70,18 @@ module Secvault
     require "secvault/rails_secrets"
   end
   
-  # Helper method to set up Secvault for Rails 7.1 applications
-  # This provides an easy way to integrate Secvault into Rails 7.1 apps
-  # that still have native Rails::Secrets functionality.
+  # Helper method to set up Secvault for older Rails versions
+  # This provides an easy way to integrate Secvault into older Rails apps
+  # that still have native Rails::Secrets functionality (like Rails 7.1).
   #
   # Usage in an initializer:
-  #   Secvault.setup_rails_71_integration!
+  #   Secvault.setup_backward_compatibility_with_older_rails!
   #
   # This will:
   # 1. Override native Rails::Secrets with Secvault implementation
   # 2. Replace Rails.application.secrets with Secvault-powered functionality
   # 3. Load secrets from config/secrets.yml automatically
-  def setup_rails_71_integration!
+  def setup_backward_compatibility_with_older_rails!
     # Override native Rails::Secrets
     if defined?(Rails::Secrets)
       Rails.send(:remove_const, :Secrets)
@@ -109,6 +114,9 @@ module Secvault
       end
     end
   end
+  
+  # Backward compatibility alias
+  alias_method :setup_rails_71_integration!, :setup_backward_compatibility_with_older_rails!
 end
 
 Secvault.install! if defined?(Rails)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: secvault
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Unnikrishnan KP