secvault 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441940b63b8d897f1ad3b84bf43168d20dcbf62017a604e201538cee0315a7ca
-  data.tar.gz: fdd75a75105b0c34efb26096499ec6ffeac7340a170d4f8fcb7188c3f0d4e3db
+  metadata.gz: 7aa65a706270754c5654d4ddac89114d5c6f59f80c2bd1480d11dc0b350a57d9
+  data.tar.gz: 9ce9a4d9661505ba37a8c827d8f5811c8b9ff0b2fab8f8a8b89bb9f53fb62618
 SHA512:
-  metadata.gz: 14fc56f53ff8729262cb5fa07bf2de96e908d7c4f6b00a1134ea2c86b3a433b220a24b3399ad43e97846cadd0bc79546780a4e0fce5318448497b62d5fba0714
-  data.tar.gz: 3e4c8387fa38263e3bf99436211b3eaadf6b3d7d2aa5ec483cc6b19fc9dcbcb9bd402b9099e800fcc8c6fb9fc09b8281875415fdd90570fbee6625d324706032
+  metadata.gz: ebd99a7e5c479c1bf98f7180414bcf7b77b45f70a19d56b3b20d734da069ed5f4d18b6855356a89d47475c6955f8ce5a4edc161e2ee13c5d4ab1494a4be38855
+  data.tar.gz: 888b561a34ff6be3798accb339d812d0456e3e10df0f4725c2c522e080ccef70c6dc23e54cae76878b5e4a67a44b4b63527b5bd0386133907b3df9a6bbec3df5

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 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,99 @@ 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 with a **super clean API**:
+
+```ruby
+# config/initializers/secvault.rb
+require "secvault"
+
+# That's it! Just pass your files array
+Secvault.setup_multi_file!([
+  'config/secrets.yml',         # Base secrets
+  'config/secrets.oauth.yml',   # OAuth & APIs
+  'config/secrets.local.yml'    # Local overrides
+])
+```
+
+**What this does automatically:**
+- ✅ Sets up Rails 7.1 compatibility (calls `setup_backward_compatibility_with_older_rails!`)
+- ✅ Loads and merges all files in order (later files override earlier ones)
+- ✅ Handles missing files gracefully
+- ✅ Adds `reload_secrets!` method in development
+- ✅ Provides logging (except in production)
+- ✅ Creates Rails.application.secrets with merged configuration
+
+**File organization example:**
+```
+config/
+├── secrets.yml           # Base application secrets
+├── secrets.oauth.yml     # OAuth providers & external APIs
+├── secrets.local.yml     # Local development overrides (gitignored)
+```
+
+**Advanced options:**
+```ruby
+# Disable reload helper or logging
+Secvault.setup_multi_file!(files, reload_method: false, logger: false)
+
+# Use Pathname objects if needed
+Secvault.setup_multi_file!([
+  Rails.root.join('config', 'secrets.yml'),
+  Rails.root.join('config', 'secrets.oauth.yml')
+])
 ```
 
 ## 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,16 +149,53 @@ 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')
+```
+
+## ERB Features & Type Conversion
+
+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 (automatically available in development):**
+```ruby
+# In Rails console - automatically added by setup_multi_file!
+reload_secrets!  # Reloads all configured files without server restart
+# 🔄 Reloaded secrets from 3 files
+
+# Also available as:
+Rails.application.reload_secrets!
+```
+
+**Check integration status:**
+```ruby
+Secvault.active?  # Returns true if Secvault is managing secrets
 ```
 
 ## Older Rails Integration
@@ -102,12 +216,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
 
-## Security
+### ⚠️ 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') %>`
 
-⚠️ 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
+### 📝 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
+  ```
+
+### 🔑 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.3.0"
+  VERSION = "2.5.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?
 
@@ -110,8 +115,87 @@ module Secvault
     end
   end
   
-  # Backward compatibility alias
+  # Set up multi-file secrets loading with a clean API
+  # Just pass an array of file paths and Secvault handles the rest
+  #
+  # Usage in an initializer:
+  #   Secvault.setup_multi_file!([
+  #     'config/secrets.yml',
+  #     'config/secrets.oauth.yml', 
+  #     'config/secrets.local.yml'
+  #   ])
+  #
+  # Options:
+  #   - files: Array of file paths (String or Pathname)
+  #   - reload_method: Add a reload helper method (default: true in development)
+  #   - logger: Enable/disable logging (default: true except in production)
+  def setup_multi_file!(files, reload_method: Rails.env.development?, logger: !Rails.env.production?)
+    # Ensure Secvault integration is active
+    setup_backward_compatibility_with_older_rails! unless active?
+    
+    # Convert strings to Pathname objects and resolve relative to Rails.root
+    file_paths = Array(files).map do |file|
+      file.is_a?(Pathname) ? file : Rails.root.join(file)
+    end
+    
+    # Set up the multi-file loading
+    Rails.application.config.after_initialize do
+      load_multi_file_secrets!(file_paths, logger: logger)
+    end
+    
+    # Add reload helper in development
+    if reload_method
+      add_reload_helper!(file_paths)
+    end
+  end
+  
+  # Load secrets from multiple files and merge them
+  def load_multi_file_secrets!(file_paths, logger: !Rails.env.production?)
+    existing_files = file_paths.select(&:exist?)
+    
+    if existing_files.any?
+      # Load and merge all secrets files
+      merged_secrets = Rails::Secrets.parse(existing_files, env: Rails.env)
+      
+      # Create ActiveSupport::OrderedOptions object for Rails compatibility
+      secrets_object = ActiveSupport::OrderedOptions.new
+      secrets_object.merge!(merged_secrets)
+      
+      # Replace Rails.application.secrets
+      Rails.application.define_singleton_method(:secrets) { secrets_object }
+      
+      # Log successful loading
+      if logger
+        file_names = existing_files.map(&:basename)
+        Rails.logger&.info "[Secvault Multi-File] Loaded #{existing_files.size} files: #{file_names.join(', ')}"
+        Rails.logger&.info "[Secvault Multi-File] Merged #{merged_secrets.keys.size} secret keys for #{Rails.env}"
+      end
+      
+      merged_secrets
+    else
+      Rails.logger&.warn "[Secvault Multi-File] No secrets files found" if logger
+      {}
+    end
+  end
+  
+  # Add reload helper method for development
+  def add_reload_helper!(file_paths)
+    # Define reload method on Rails.application
+    Rails.application.define_singleton_method(:reload_secrets!) do
+      Secvault.load_multi_file_secrets!(file_paths, logger: true)
+      puts "🔄 Reloaded secrets from #{file_paths.size} files"
+      true
+    end
+    
+    # Also make it available as a top-level method
+    Object.define_method(:reload_secrets!) do
+      Rails.application.reload_secrets!
+    end
+  end
+  
+  # Backward compatibility aliases
   alias_method :setup_rails_71_integration!, :setup_backward_compatibility_with_older_rails!
+  alias_method :setup_multi_files!, :setup_multi_file!  # Alternative name
 end
 
 Secvault.install! if defined?(Rails)

metadata

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