legion-settings 1.2.2 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e6bfc5465268327a07174136c9b4cc7eb8793345bc43b61bbefbf99fdf2406a
-  data.tar.gz: 9e6b1384a02334a6aecbe50474f184bfb7996d16efe36d9b80744a4feb6171bc
+  metadata.gz: cb0e2c44578e9e5b6cbb495c5160e1a37c067ea5692979e50e89494d33da9888
+  data.tar.gz: ebca4fdb1fb58e2fa315620209ccbe5f5302057a7dc0d4a256f9689ea8d5d8b0
 SHA512:
-  metadata.gz: c8d084a1a0b75578ada3bb4f765bf7948ed9f9969e03717d10bf357d82895d1717b7e634e5f7ce8385bc3f1f4734e7e8e0d00a24ad4596a04f72f950c1ec84ec
-  data.tar.gz: 6f2ed8e7febb6d6a9f9e36b3d86a5522230f7254bf46aaa4e966c9d60b91f71f80a8a2e46de9510f77bedbda53d759426d087c71fdecbb15c2ef2c1efdb08298
+  metadata.gz: 738f2ced6bf58fcb2d9ad4fca307d63abea4241bd6c5e788ff3ee47346f8f1054fd1cceb94d86e2f393f7985a0a835076513b94de730a89e9e233d923d5c1775
+  data.tar.gz: ac60c369c84bd0dcb53b84f5fcdf9440fcd25ea00d15bb32386b67a4b999ceead7dde040fa66de53c9e6b06a5e99628b674923d0503dcbbe945a5b30a7d88bb6

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Legion::Settings Changelog
 
+## [1.3.1] - 2026-03-16
+
+### Added
+- `lease://name#key` URI scheme in secret resolver for dynamic Vault leases
+- Delegates to `Legion::Crypt::LeaseManager` for lease data lookup
+- Registers reverse references for push-back on credential rotation
+
+## [1.3.0] - 2026-03-16
+
+### Added
+- Universal secret resolver: `vault://` and `env://` URI references in any settings value
+- Fallback chain support via arrays (first non-nil wins)
+- `Legion::Settings.resolve_secrets!` method for explicit resolution phase
+- Vault read caching within a single resolution pass
+
 ## [1.2.2] - 2026-03-16
 
 ### Added

data/CLAUDE.md

@@ -68,6 +68,7 @@ Legion::Settings (singleton module)
 | `lib/legion/settings/schema.rb` | Type inference, validation logic, unknown key detection (Levenshtein) |
 | `lib/legion/settings/validation_error.rb` | Error collection and formatted reporting |
 | `lib/legion/settings/os.rb` | OS detection helpers |
+| `lib/legion/settings/resolver.rb` | Secret resolution: `vault://` and `env://` URI references, fallback chains |
 | `lib/legion/settings/version.rb` | VERSION constant |
 | `spec/legion/settings_spec.rb` | Core settings module tests |
 | `spec/legion/settings_module_spec.rb` | Module-level accessor and merge tests |
@@ -76,6 +77,45 @@ Legion::Settings (singleton module)
 | `spec/legion/settings/validation_error_spec.rb` | Error formatting tests |
 | `spec/legion/settings/integration_spec.rb` | End-to-end validation tests |
 | `spec/legion/settings/role_defaults_spec.rb` | Role profile default settings tests |
+| `spec/legion/settings/resolver_spec.rb` | Secret resolver tests (env://, vault://, lease://, fallback chains) |
+
+## Secret Resolution
+
+Settings values can reference external secret sources using URI syntax. Resolved in-place via `Legion::Settings.resolve_secrets!` (called automatically after `Legion::Crypt.start` in the boot sequence).
+
+### URI Schemes
+
+| Scheme | Format | Resolution |
+|--------|--------|------------|
+| `vault://` | `vault://path/to/secret#key` | `Legion::Crypt.read(path)[key]` (static KV secrets) |
+| `env://` | `env://ENV_VAR_NAME` | `ENV['ENV_VAR_NAME']` |
+| `lease://` | `lease://name#key` | `Legion::Crypt::LeaseManager.instance.fetch(name, key)` (dynamic Vault leases) |
+| *(plain string)* | `"guest"` | Returned as-is |
+
+### Fallback Chains
+
+Array values are tried in order — first non-nil wins:
+
+```json
+{
+  "transport": {
+    "connection": {
+      "password": ["vault://secret/data/rabbitmq#password", "env://RABBITMQ_PASSWORD", "guest"]
+    }
+  }
+}
+```
+
+### Logging Strategy
+
+- Vault not connected + vault refs exist: one summary warning with count
+- Individual vault path failures: debug level
+- Entire chain resolves to nil: one warning per key path
+- Success: info summary with resolved counts
+
+### Implementation
+
+`Legion::Settings::Resolver` module with `module_function`. Called via `Legion::Settings.resolve_secrets!` which delegates to `Resolver.resolve_secrets!(@loader.to_hash)`. Vault reads are cached by path within a single resolution pass.
 
 ## Role in LegionIO
 

data/README.md

@@ -28,11 +28,40 @@ Legion::Settings[:transport][:connection][:host]
 ### Config Paths (checked in order)
 
 1. `/etc/legionio/`
-2. `~/legionio/`
-3. `./settings/`
+2. `~/.legionio/settings/`
+3. `~/legionio/`
+4. `./settings/`
 
 Each Legion module registers its own defaults via `merge_settings` during startup.
 
+### Secret Resolution
+
+Settings values can reference external secret sources using URI syntax. Two schemes are supported:
+
+| Scheme | Format | Resolution |
+|--------|--------|------------|
+| `vault://` | `vault://path/to/secret#key` | Reads from HashiCorp Vault via `Legion::Crypt` |
+| `env://` | `env://ENV_VAR_NAME` | Reads from environment variable |
+
+Array values act as fallback chains — the first non-nil result wins:
+
+```json
+{
+  "transport": {
+    "connection": {
+      "password": ["vault://secret/data/rabbitmq#password", "env://RABBITMQ_PASSWORD", "guest"]
+    }
+  }
+}
+```
+
+Call `Legion::Settings.resolve_secrets!` to resolve all URIs in-place. In the LegionIO boot sequence this is called automatically after `Legion::Crypt.start`. The `env://` scheme works even when Vault is not connected.
+
+```ruby
+Legion::Settings.resolve_secrets!
+# All vault:// and env:// references are now replaced with their resolved values
+```
+
 ### Schema Validation
 
 Types are inferred automatically from default values. Optional constraints can be added:

data/lib/legion/settings/resolver.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    module Resolver
+      VAULT_PATTERN  = %r{\Avault://(.+?)#(.+)\z}
+      ENV_PATTERN    = %r{\Aenv://(.+)\z}
+      LEASE_PATTERN  = %r{\Alease://(.+?)#(.+)\z}
+      URI_PATTERN    = %r{\A(?:vault|env|lease)://}
+
+      module_function
+
+      def resolve_secrets!(settings_hash)
+        return settings_hash unless settings_hash.is_a?(Hash)
+
+        @vault_available = vault_connected?
+        @vault_cache     = {}
+
+        vault_count = count_vault_refs(settings_hash)
+        log_warn("Vault not connected — #{vault_count} vault:// reference(s) will not be resolved") if vault_count.positive? && !@vault_available
+
+        lease_count = count_lease_refs(settings_hash)
+        log_warn("LeaseManager not available — #{lease_count} lease:// reference(s) will not be resolved") if lease_count.positive? && !lease_manager_available?
+
+        resolved = 0
+        unresolved = 0
+        walk(settings_hash, path: '') do |result|
+          if result == :resolved
+            resolved += 1
+          elsif result == :unresolved
+            unresolved += 1
+          end
+        end
+
+        log_info("Settings resolver: #{resolved} resolved, #{unresolved} unresolved") if resolved.positive? || unresolved.positive?
+
+        settings_hash
+      end
+
+      def resolve_value(value)
+        case value
+        when String
+          return value unless value.match?(URI_PATTERN)
+
+          resolve_single(value)
+        when Array
+          return value unless resolvable_chain?(value)
+
+          resolve_chain(value)
+        else
+          value
+        end
+      end
+
+      def resolve_single(str)
+        if (m = str.match(VAULT_PATTERN))
+          resolve_vault(m[1], m[2])
+        elsif (m = str.match(LEASE_PATTERN))
+          resolve_lease(m[1], m[2])
+        elsif (m = str.match(ENV_PATTERN))
+          ENV.fetch(m[1], nil)
+        else
+          str
+        end
+      end
+
+      def resolve_chain(arr)
+        arr.each do |entry|
+          result = if entry.is_a?(String) && entry.match?(URI_PATTERN)
+                     resolve_single(entry)
+                   else
+                     entry
+                   end
+          return result unless result.nil?
+        end
+        nil
+      end
+
+      def has_vault_refs?(hash) # rubocop:disable Naming/PredicatePrefix
+        count_vault_refs(hash).positive?
+      end
+
+      def count_vault_refs(hash)
+        return 0 unless hash.is_a?(Hash)
+
+        hash.sum do |_key, value|
+          case value
+          when String then value.match?(VAULT_PATTERN) ? 1 : 0
+          when Array  then value.count { |v| v.is_a?(String) && v.match?(VAULT_PATTERN) }
+          when Hash   then count_vault_refs(value)
+          else 0
+          end
+        end
+      end
+
+      def vault_connected?
+        return false unless defined?(Legion::Crypt)
+        return false unless defined?(Legion::Settings)
+
+        Legion::Settings[:crypt][:vault][:connected] == true
+      rescue StandardError
+        false
+      end
+
+      def walk(hash, path:, &block)
+        hash.each do |key, value|
+          current_path = path.empty? ? key.to_s : "#{path}.#{key}"
+
+          case value
+          when Hash
+            walk(value, path: current_path, &block)
+          when String
+            next unless value.match?(URI_PATTERN)
+
+            resolved = resolve_single(value)
+            if resolved.nil?
+              log_warn("Settings resolver: could not resolve #{current_path} (#{value})")
+              block&.call(:unresolved)
+            else
+              hash[key] = resolved
+              register_lease_ref(value, current_path) if value.match?(LEASE_PATTERN)
+              block&.call(:resolved)
+            end
+          when Array
+            next unless resolvable_chain?(value)
+
+            resolved = resolve_chain(value)
+            if resolved.nil?
+              log_warn("Settings resolver: fallback chain exhausted for #{current_path}")
+              block&.call(:unresolved)
+            else
+              hash[key] = resolved
+              register_lease_refs_from_chain(value, current_path)
+              block&.call(:resolved)
+            end
+          end
+        end
+      end
+
+      def resolve_vault(path, key)
+        return nil unless @vault_available
+
+        @vault_cache[path] ||= begin
+          Legion::Crypt.read(path)
+        rescue StandardError => e
+          log_debug("Settings resolver: vault read failed for #{path}: #{e.message}")
+          nil
+        end
+
+        data = @vault_cache[path]
+        return nil unless data.is_a?(Hash)
+
+        data[key.to_sym] || data[key.to_s]
+      end
+
+      def resolve_lease(name, key)
+        return nil unless lease_manager_available?
+
+        Legion::Crypt::LeaseManager.instance.fetch(name, key)
+      rescue StandardError => e
+        log_debug("Settings resolver: lease fetch failed for #{name}##{key}: #{e.message}")
+        nil
+      end
+
+      def lease_manager_available?
+        defined?(Legion::Crypt::LeaseManager)
+      rescue StandardError
+        false
+      end
+
+      def resolvable_chain?(arr)
+        arr.any? { |v| v.is_a?(String) && v.match?(URI_PATTERN) }
+      end
+
+      def register_lease_ref(value, path_string)
+        return unless lease_manager_available?
+
+        m = value.match(LEASE_PATTERN)
+        return unless m
+
+        path_parts = path_string.split('.').map(&:to_sym)
+        Legion::Crypt::LeaseManager.instance.register_ref(m[1], m[2], path_parts)
+      rescue StandardError
+        nil
+      end
+
+      def register_lease_refs_from_chain(arr, path_string)
+        return unless lease_manager_available?
+
+        arr.each do |entry|
+          next unless entry.is_a?(String)
+
+          register_lease_ref(entry, path_string) if entry.match?(LEASE_PATTERN)
+        end
+      end
+
+      def count_lease_refs(hash)
+        return 0 unless hash.is_a?(Hash)
+
+        hash.sum do |_key, value|
+          case value
+          when String then value.match?(LEASE_PATTERN) ? 1 : 0
+          when Array  then value.count { |v| v.is_a?(String) && v.match?(LEASE_PATTERN) }
+          when Hash   then count_lease_refs(value)
+          else 0
+          end
+        end
+      end
+
+      def log_info(message)
+        if defined?(Legion::Logging)
+          Legion::Logging.info(message)
+        else
+          $stdout.puts(message)
+        end
+      end
+
+      def log_warn(message)
+        if defined?(Legion::Logging)
+          Legion::Logging.warn(message)
+        else
+          warn(message)
+        end
+      end
+
+      def log_debug(message)
+        if defined?(Legion::Logging)
+          Legion::Logging.debug(message)
+        else
+          $stdout.puts(message)
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Settings
-    VERSION = '1.2.2'
+    VERSION = '1.3.1'
   end
 end

data/lib/legion/settings.rb

@@ -79,6 +79,12 @@ module Legion
         warn_validation_errors(errors)
       end
 
+      def resolve_secrets!
+        @loader = load if @loader.nil?
+        require 'legion/settings/resolver'
+        Resolver.resolve_secrets!(@loader.to_hash)
+      end
+
       def schema
         @schema ||= Schema.new
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.1
 platform: ruby
 authors:
 - Esity
@@ -46,6 +46,7 @@ files:
 - lib/legion/settings.rb
 - lib/legion/settings/loader.rb
 - lib/legion/settings/os.rb
+- lib/legion/settings/resolver.rb
 - lib/legion/settings/schema.rb
 - lib/legion/settings/validation_error.rb
 - lib/legion/settings/version.rb