secvault 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18d7c81d380aa63a8092f4bd91a438ee3e02282695b6fcbe6841ffbb81a30a9b
-  data.tar.gz: 2dbe018b171e0840e9a6047027fcf8e60ef73ec60867e4f6f4f97240df74f126
+  metadata.gz: 804b4325743910209d494c3c81b4f5f0dc8cf89dd802b4b424544923e42cee34
+  data.tar.gz: 6c456cdd91bf12b27ab70922deb6736c42c8afdeb3e91c7173428c791441ff2c
 SHA512:
-  metadata.gz: c864336bbb71f184bf09e9f3bc0c191cbd7f7d750ee5a9c541cc3711b0ddc0cc608103e574dffd940b64dc814b4d5b5f433940ef0adf6235e3d17caf9f5784ce
-  data.tar.gz: 6c62bb91d5a9a0ca1ac0a984f94c92d11c9815d8832e371b7b362d2d6142e1a5f6ea5b058ce8d7762708c271c4cfe848b753d8ea2c6c1dbf47ace950c6df16fd
+  metadata.gz: 82efdd937655a3ba4eaefe8d732df4e2def7fd12a91302b182d1c300f1a17c10031339a53efe14af1f7c23bdfc40bdc44d43f578bc487a4e425551b75169f1c0
+  data.tar.gz: 0bf0eab87edf50ef01b0d5f0989d8403cd2b96795a393504de87875541ef458fbe3342ba2d8d0e8316b252259bbfee00abff8d1cb265bf0d73cdd951e979c27a

data/README.md

@@ -7,16 +7,6 @@ Restores the classic Rails `secrets.yml` functionality that was removed in Rails
 - **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
@@ -86,38 +76,35 @@ production:
 
 ## Multi-File Configuration
 
-Organize secrets across multiple files for better maintainability:
+Organize secrets across multiple files with a **super clean API**:
 
 ```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
+# 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
+])
 ```
 
-**File organization example:**
-```
-config/
-├── secrets.yml           # Base application secrets
-├── secrets.oauth.yml     # OAuth providers & external APIs
-├── secrets.local.yml     # Local development overrides (gitignored)
+**What this does:**
+- ✅ Loads and merges all files in order (later files override earlier ones)
+- ✅ Handles missing files gracefully
+- ✅ Creates Rails.application.secrets with merged configuration
+
+**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
@@ -152,7 +139,7 @@ dev_secrets = Rails::Secrets.load(env: 'development')
 
 ## ERB Features & Type Conversion
 
-Secvault supports powerful ERB templating with automatic type conversion:
+Secvault supports ERB templating with automatic type conversion:
 
 ```yaml
 production:
@@ -175,10 +162,14 @@ production:
 
 ## Development Tools
 
-**Hot-reload secrets (development only):**
+**Hot-reload secrets (automatically available in development):**
 ```ruby
-# In Rails console or code
-reload_secrets!  # Reloads all secrets files without server restart
+# 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:**
@@ -213,60 +204,12 @@ else
 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') %>`
 
-### 📝 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
 
 MIT License - see [LICENSE](https://opensource.org/licenses/MIT)

data/USAGE_EXAMPLES.md

@@ -0,0 +1,65 @@
+# Secvault API
+
+Secvault provides separate control over secrets loading and Rails integration.
+
+## Core Methods
+
+### `Secvault.start!(files: [])`
+
+Loads secrets from YAML files. Returns `true`/`false`.
+
+- **Default**: Uses `config/secrets.yml` if `files` is empty
+- **Access**: Secrets available via `Secvault.secrets`
+- **Non-invasive**: Does not modify `Rails.application.secrets`
+
+### `Secvault.integrate_with_rails!`
+
+Replaces `Rails.application.secrets` with Secvault's loaded secrets. Returns `true`/`false`.
+
+### `Secvault.secrets`
+
+Access to loaded secrets as `ActiveSupport::OrderedOptions`.
+
+### Status Methods
+
+- `Secvault.active?` - Returns `true` if secrets have been loaded
+- `Secvault.rails_integrated?` - Returns `true` if Rails integration is active
+
+## Usage
+
+### Standalone
+
+```ruby
+# Load secrets independently
+Secvault.start!
+api_key = Secvault.secrets.api_key
+```
+
+### With Rails Integration
+
+```ruby
+# Load and integrate with Rails
+Secvault.start!
+Secvault.integrate_with_rails!
+api_key = Rails.application.secrets.api_key
+```
+
+### Multiple Files
+
+```ruby
+# Files are deep-merged in order
+Secvault.start!(files: [
+  'config/shared_secrets.yml',
+  'config/secrets.yml'
+])
+```
+
+### Error Handling
+
+```ruby
+if Secvault.start!(files: ['config/secrets.yml'])
+  if Secvault.integrate_with_rails!
+    # Both operations successful
+  end
+end
+```

data/lib/secvault/secrets.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/hash/deep_merge"
 require "active_support/ordered_options"
 require "pathname"
 require "erb"
@@ -89,9 +90,9 @@ module Secvault
           
           secrets ||= {}
           
-          # Merge shared secrets first, then environment-specific
-          all_secrets.merge!(secrets["shared"].deep_symbolize_keys) if secrets["shared"]
-          all_secrets.merge!(secrets[env].deep_symbolize_keys) if secrets[env]
+          # Merge shared secrets first, then environment-specific (using deep merge)
+          all_secrets.deep_merge!(secrets["shared"].deep_symbolize_keys) if secrets["shared"]
+          all_secrets.deep_merge!(secrets[env].deep_symbolize_keys) if secrets[env]
         end
       end
 

data/lib/secvault/version.rb

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

data/lib/secvault.rb

@@ -57,9 +57,22 @@ module Secvault
   class Error < StandardError; end
 
   extend self
+  
+  # Internal storage for loaded secrets
+  @@loaded_secrets = nil
 
-  # Check if Secvault is currently active in the Rails application
+  # Access to loaded secrets without Rails integration
+  def secrets
+    @@loaded_secrets || ActiveSupport::OrderedOptions.new
+  end
+  
+  # Check if Secvault is currently active (started)
   def active?
+    @@loaded_secrets != nil
+  end
+  
+  # Check if Secvault is integrated with Rails.application.secrets
+  def rails_integrated?
     defined?(Rails) && Rails::Secrets == Secvault::RailsSecrets
   end
 
@@ -115,8 +128,174 @@ 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 into Secvault.secrets only (no Rails integration)
+  def load_secrets_only!(files, logger: !Rails.env.production?)
+    # 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
+    
+    existing_files = file_paths.select(&:exist?)
+    
+    if existing_files.any?
+      # Load and merge all secrets files using Secvault's parser directly
+      merged_secrets = Secvault::Secrets.parse(existing_files, env: Rails.env)
+      
+      # Store in Secvault.secrets (ActiveSupport::OrderedOptions for compatibility)
+      @@loaded_secrets = ActiveSupport::OrderedOptions.new
+      @@loaded_secrets.merge!(merged_secrets)
+      
+      # Log successful loading
+      if logger
+        file_names = existing_files.map(&:basename)
+        Rails.logger&.info "[Secvault] Loaded #{existing_files.size} files: #{file_names.join(', ')}"
+        Rails.logger&.info "[Secvault] Parsed #{merged_secrets.keys.size} secret keys for #{Rails.env}"
+      end
+      
+      true
+    else
+      Rails.logger&.warn "[Secvault] No secrets files found" if logger
+      @@loaded_secrets = ActiveSupport::OrderedOptions.new
+      false
+    end
+  end
+  
+  # Load secrets from multiple files and merge them (with Rails integration)
+  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
+  
+  # Start Secvault and load secrets (without Rails integration)
+  # 
+  # Usage:
+  #   Secvault.start!                                    # Uses config/secrets.yml only
+  #   Secvault.start!(files: [])                        # Same as above
+  #   Secvault.start!(files: ['path/to/secrets.yml'])   # Custom single file
+  #   Secvault.start!(files: ['gem.yml', 'app.yml'])    # Multiple files
+  #
+  # Access loaded secrets via: Secvault.secrets.your_key
+  # To integrate with Rails.application.secrets, call: Secvault.integrate_with_rails!
+  #
+  # Options:
+  #   - files: Array of file paths (String or Pathname). Defaults to ['config/secrets.yml']
+  #   - logger: Enable logging (default: true except production)
+  def start!(files: [], logger: !Rails.env.production?)
+    begin
+      # Default to host app's config/secrets.yml if no files specified
+      files_to_load = files.empty? ? ['config/secrets.yml'] : files
+      
+      # Load secrets into Secvault.secrets (completely independent of Rails)
+      load_secrets_only!(files_to_load, logger: logger)
+      
+      true
+    rescue => e
+      Rails.logger&.error "[Secvault] Failed to start: #{e.message}" if defined?(Rails)
+      false
+    end
+  end
+  
+  # Integrate loaded secrets with Rails.application.secrets
+  def integrate_with_rails!
+    return false unless @@loaded_secrets
+    
+    begin
+      # Set up Rails::Secrets to use Secvault's parser (only when integrating)
+      unless rails_integrated?
+        if defined?(Rails::Secrets)
+          Rails.send(:remove_const, :Secrets)
+        end
+        Rails.const_set(:Secrets, Secvault::RailsSecrets)
+      end
+      
+      # Replace Rails.application.secrets with Secvault's loaded secrets
+      Rails.application.define_singleton_method(:secrets) do
+        Secvault.secrets
+      end
+      
+      Rails.logger&.info "[Secvault] Integrated with Rails.application.secrets" unless Rails.env.production?
+      true
+    rescue => e
+      Rails.logger&.error "[Secvault] Failed to integrate with Rails: #{e.message}" if defined?(Rails)
+      false
+    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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: secvault
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Unnikrishnan KP
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-22 00:00:00.000000000 Z
+date: 2025-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -54,6 +54,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- USAGE_EXAMPLES.md
 - lib/secvault.rb
 - lib/secvault/generators/secrets_generator.rb
 - lib/secvault/rails_secrets.rb