secvault 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441940b63b8d897f1ad3b84bf43168d20dcbf62017a604e201538cee0315a7ca
-  data.tar.gz: fdd75a75105b0c34efb26096499ec6ffeac7340a170d4f8fcb7188c3f0d4e3db
+  metadata.gz: 18d7c81d380aa63a8092f4bd91a438ee3e02282695b6fcbe6841ffbb81a30a9b
+  data.tar.gz: 2dbe018b171e0840e9a6047027fcf8e60ef73ec60867e4f6f4f97240df74f126
 SHA512:
-  metadata.gz: 14fc56f53ff8729262cb5fa07bf2de96e908d7c4f6b00a1134ea2c86b3a433b220a24b3399ad43e97846cadd0bc79546780a4e0fce5318448497b62d5fba0714
-  data.tar.gz: 3e4c8387fa38263e3bf99436211b3eaadf6b3d7d2aa5ec483cc6b19fc9dcbcb9bd402b9099e800fcc8c6fb9fc09b8281875415fdd90570fbee6625d324706032
+  metadata.gz: c864336bbb71f184bf09e9f3bc0c191cbd7f7d750ee5a9c541cc3711b0ddc0cc608103e574dffd940b64dc814b4d5b5f433940ef0adf6235e3d17caf9f5784ce
+  data.tar.gz: 6c62bb91d5a9a0ca1ac0a984f94c92d11c9815d8832e371b7b362d2d6142e1a5f6ea5b058ce8d7762708c271c4cfe848b753d8ea2c6c1dbf47ace950c6df16fd

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,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,16 +141,49 @@ 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 (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
@@ -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
+```
 
-## Security
+## 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)
+```
 
-⚠️ 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
+**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') %>`
+
+### 📝 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.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?
 

metadata

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