legion-crypt 1.4.19 → 1.4.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3a746c03498b392437f0d7db81caca5f6daa84aeda465bbf0db71bb898d25f1
-  data.tar.gz: d27dfcdfa9032fa6bc8df4174f370c7896151c746bf8b810421d1c28d5d8e51b
+  metadata.gz: ec95cba72f1350ed61da82d296c14ddf6729cce61785ac908fbcf98256935e48
+  data.tar.gz: 15770beb8714e14a4ff14c42473a9f55ef0de549683e299b6b4d044da513249e
 SHA512:
-  metadata.gz: 9e3a72a7a2fc6b78439f582b33c3c667fb40f1ef86c8a0201fb53e38d2d122e3689fa3496e11df36e5085a551753d58864a8033bc2cb028662922d87ce7afc9a
-  data.tar.gz: ab485a6da390007f060067bcca2863a5585fd6845f2dfc023658d48c6195364af7f99bf86f2492830d7991ae6a600a43fbd819d715412ca3f9c210fa95a830e3
+  metadata.gz: aea19ef52f31d1d7b5e8ddd8392749fd40e7305eef410958ae9012128dd8c79698df37baf557ef25c0b34ebf8ba6821ef42900346a28d73dee5241c44024039a
+  data.tar.gz: ba9ab25d478aaeed112a41362ca4b587ea0acacf1745f5518f4867a936372567dc9f7bb906b7855a5596973d020da1629f7349608d81e7ec907e1965a4777686

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Legion::Crypt
 
+## [1.4.22] - 2026-03-27
+
+### Changed
+- Replace split `log.error(e.message); log.error(e.backtrace)` patterns with single `Legion::Logging.log_exception` calls in `vault.rb`, `cluster_secret.rb`, and `settings.rb` for structured exception events
+- Guard all `log_exception` call sites in `vault.rb`, `settings.rb`, and `cluster_secret.rb` with `Legion::Logging` presence checks (`defined?` in `vault.rb`/`cluster_secret.rb`, `Legion.const_defined?('Logging')` in `settings.rb`) plus `Legion::Logging.respond_to?(:log_exception)`; fall back to `Legion::Logging.fatal`/`error` or `warn` to preserve structured logging in environments where `log_exception` is unavailable
+- `from_transport` and `cs` rescue blocks in `cluster_secret.rb` now use the same 4-branch guard (log_exception / Logging.error / Logging.warn / Kernel.warn) and explicitly return `nil` to preserve expected return types
+- Fallback `.error`/`.warn`/`Kernel.warn` branches in `from_transport` and `cs` include the first 10 backtrace lines for debuggability parity with the prior `e.backtrace[0..10]` logging; `Vault#connect_vault` warn fallback omits backtrace to keep health-check failure messages concise
+- `cs` rescue adds final `Kernel.warn` fallback so exceptions are never silently swallowed when `Legion::Logging` is absent
+
+### Added
+- Specs for `connect_vault` rescue logging: asserts `false` return and covers log_exception / Logging.error / warn fallback branches when `Vault.sys.health_status` raises
+- Specs for `from_transport` and `cs` rescue paths: asserts `nil` return and covers all logging fallback branches (including `Kernel.warn`) plus `Legion::Logging` absent case
+- Duplicate invocation eliminated in rescue-path specs: single call stored in `result`, both no-raise and return value asserted on that one call
+
+## [1.4.20] - 2026-03-27
+
+### Fixed
+- `Vault#read`: unwrap KV v2 response envelope — `logical.read` returns `{data: {keys}, metadata: {}}` for KV v2 mounts; the nested `:data` key is now auto-detected and unwrapped
+
+### Added
+- Debug logging throughout Vault auth, read, and cluster connection paths (`vault.rb`, `vault_cluster.rb`, `kerberos_auth.rb`, `lease_manager.rb`)
+- `Vault#log_read_context`: logs path and namespace context for each Vault read
+- `Vault#unwrap_kv_v2`: detects and unwraps KV v2 envelope pattern
+- `VaultCluster`: debug logging for cluster connection, client build, and Kerberos auth flow
+- `KerberosAuth`: debug logging for SPN, token exchange, policies, and renewal metadata
+- `LeaseManager`: debug logging for lease fetch, renewal, and revocation
+
 ## [1.4.19] - 2026-03-26
 
 ### Fixed

data/README.md

@@ -2,7 +2,7 @@
 
 Encryption, secrets management, JWT token management, and HashiCorp Vault integration for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides AES-256-CBC message encryption, RSA key pair generation, cluster secret management, JWT issue/verify operations, Vault token lifecycle management, and multi-cluster Vault connectivity.
 
-**Version**: 1.4.15
+**Version**: 1.4.22
 
 ## Installation
 

data/lib/legion/crypt/cluster_secret.rb

@@ -64,8 +64,14 @@ module Legion
         Legion::Logging.error 'Cluster secret is still unknown!'
         nil
       rescue StandardError => e
-        Legion::Logging.error e.message
-        Legion::Logging.error e.backtrace[0..10]
+        if defined?(Legion::Logging) && Legion::Logging.respond_to?(:log_exception)
+          Legion::Logging.log_exception(e, lex: 'crypt', component_type: :helper)
+        elsif defined?(Legion::Logging) && Legion::Logging.respond_to?(:error)
+          Legion::Logging.error "from_transport failed: #{e.class}=#{e.message}\n#{Array(e.backtrace).first(10).join("\n")}"
+        else
+          warn "from_transport failed: #{e.class}=#{e.message}\n#{Array(e.backtrace).first(10).join("\n")}"
+        end
+        nil
       end
 
       def force_cluster_secret
@@ -114,8 +120,19 @@ module Legion
       def cs
         @cs ||= Digest::SHA256.digest(find_cluster_secret)
       rescue StandardError => e
-        Legion::Logging.error e.message
-        Legion::Logging.error e.backtrace[0..10]
+        if defined?(Legion::Logging) && Legion::Logging.respond_to?(:log_exception)
+          Legion::Logging.log_exception(e, lex: 'crypt', component_type: :helper)
+        elsif defined?(Legion::Logging) && Legion::Logging.respond_to?(:error)
+          backtrace = Array(e.backtrace).first(10).join("\n")
+          Legion::Logging.error "Legion::Crypt::ClusterSecret#cs failed: #{e.class}: #{e.message}\n#{backtrace}"
+        elsif defined?(Legion::Logging) && Legion::Logging.respond_to?(:warn)
+          backtrace = Array(e.backtrace).first(10).join("\n")
+          Legion::Logging.warn "Legion::Crypt::ClusterSecret#cs failed: #{e.class}: #{e.message}\n#{backtrace}"
+        else
+          backtrace = Array(e.backtrace).first(10).join("\n")
+          ::Kernel.warn "Legion::Crypt::ClusterSecret#cs failed: #{e.class}: #{e.message}\n#{backtrace}"
+        end
+        nil
       end
 
       def validate_hex(value, length = secret_length)

data/lib/legion/crypt/kerberos_auth.rb

@@ -17,10 +17,19 @@ module Legion
       def self.login(vault_client:, service_principal:, auth_path: DEFAULT_AUTH_PATH)
         raise GemMissingError, 'lex-kerberos gem is required for Kerberos auth' unless spnego_available?
 
+        log_debug("login: SPN=#{service_principal}, auth_path=#{auth_path}")
+        addr = vault_client.respond_to?(:address) ? vault_client.address : 'n/a'
+        ns   = vault_client.respond_to?(:namespace) ? vault_client.namespace.inspect : 'n/a'
+        log_debug("login: vault_client.address=#{addr}, namespace=#{ns}")
+
         @kerberos_principal = nil
         token = obtain_token(service_principal)
+        log_debug("login: SPNEGO token obtained (#{token.length} chars)")
+
         result = exchange_token(vault_client, token, auth_path)
         @kerberos_principal = result[:metadata]&.dig('username') || result[:metadata]&.dig(:username)
+        log_debug("login: authenticated as #{@kerberos_principal.inspect}, policies=#{result[:policies].inspect}")
+        log_debug("login: renewable=#{result[:renewable]}, ttl=#{result[:lease_duration]}s")
         result
       end
 
@@ -41,6 +50,11 @@ module Legion
         @kerberos_principal = nil
       end
 
+      def self.log_debug(message)
+        Legion::Logging.debug("KerberosAuth: #{message}") if defined?(Legion::Logging)
+      end
+      private_class_method :log_debug
+
       class << self
         private
 
@@ -58,6 +72,7 @@ module Legion
 
           # The Vault Kerberos plugin reads the SPNEGO token from the HTTP
           # Authorization header, not the JSON body.
+          log_debug("exchange_token: PUT /v1/#{auth_path} (namespace=#{vault_client.respond_to?(:namespace) ? vault_client.namespace.inspect : 'n/a'})")
           json = vault_client.put(
             "/v1/#{auth_path}",
             '{}',
@@ -75,6 +90,7 @@ module Legion
             metadata:       auth.metadata
           }
         rescue ::Vault::HTTPClientError => e
+          log_debug("exchange_token: HTTP error: #{e.message}")
           raise AuthError, "Vault Kerberos auth failed: #{e.message}"
         end
       end

data/lib/legion/crypt/lease_manager.rb

@@ -27,7 +27,10 @@ module Legion
 
           begin
             response = logical.read(path)
-            next unless response
+            unless response
+              log_warn("LeaseManager: no data at '#{name}' (#{path}) — path may not exist or role not configured")
+              next
+            end
 
             @lease_cache[name] = response.data || {}
             @active_leases[name] = {
@@ -44,6 +47,10 @@ module Legion
         end
       end
 
+      def fetched_count
+        @active_leases.size
+      end
+
       def fetch(name, key)
         data = @lease_cache[name.to_sym] || @lease_cache[name.to_s]
         return nil unless data

data/lib/legion/crypt/settings.rb

@@ -67,9 +67,10 @@ end
 begin
   Legion::Settings.merge_settings('crypt', Legion::Crypt::Settings.default) if Legion.const_defined?('Settings')
 rescue StandardError => e
-  if Legion.const_defined?('Logging') && Legion::Logging.method_defined?(:fatal)
-    Legion::Logging.fatal(e.message)
-    Legion::Logging.fatal(e.backtrace)
+  if Legion.const_defined?('Logging') && Legion::Logging.respond_to?(:log_exception)
+    Legion::Logging.log_exception(e, lex: 'crypt', component_type: :helper, level: :fatal)
+  elsif Legion.const_defined?('Logging') && Legion::Logging.respond_to?(:fatal)
+    Legion::Logging.fatal("crypt settings merge error: #{e.class}: #{e.message}\n#{Array(e.backtrace).join("\n")}")
   else
     puts e.message
     puts e.backtrace

data/lib/legion/crypt/vault.rb

@@ -37,30 +37,47 @@ module Legion
           Legion::Logging.info "Vault connected at #{::Vault.address}" if defined?(Legion::Logging)
         end
       rescue StandardError => e
-        Legion::Logging.error e.message
+        if defined?(Legion::Logging) && Legion::Logging.respond_to?(:log_exception)
+          Legion::Logging.log_exception(e, lex: 'crypt', component_type: :helper)
+        elsif defined?(Legion::Logging) && Legion::Logging.respond_to?(:error)
+          Legion::Logging.error "Vault connection failed: #{e.class}=#{e.message}\n#{Array(e.backtrace).first(10).join("\n")}"
+        else
+          warn "Vault connection failed: #{e.class}=#{e.message}"
+        end
         Legion::Settings[:crypt][:vault][:connected] = false
         false
       end
 
       def read(path, type = 'legion')
         full_path = type.nil? || type.empty? ? "#{type}/#{path}" : path
-        Legion::Logging.debug "Vault read: #{full_path}" if defined?(Legion::Logging)
+        log_read_context(full_path)
         lease = logical_client.read(full_path)
-        add_session(path: lease.lease_id) if lease.respond_to? :lease_id
-        lease.data
+        if lease.nil?
+          log_vault_debug("Vault read: #{full_path} returned nil")
+          return nil
+        end
+        add_session(path: lease.lease_id) if lease.respond_to?(:lease_id) && lease.lease_id && !lease.lease_id.empty?
+
+        data = lease.data
+        log_vault_debug("Vault read: #{full_path} returned keys=#{data&.keys&.inspect}")
+        unwrap_kv_v2(data, full_path)
       rescue StandardError => e
-        Legion::Logging.warn "Vault read failed at #{full_path}: #{e.message}" if defined?(Legion::Logging)
+        Legion::Logging.warn "Vault read failed at #{full_path}: #{e.class}=#{e.message}" if defined?(Legion::Logging)
         raise
       end
 
       def get(path)
-        Legion::Logging.debug "Vault kv get: #{path}" if defined?(Legion::Logging)
+        Legion::Logging.debug "Vault kv get: path=#{path}" if defined?(Legion::Logging)
         result = kv_client.read(path)
-        return nil if result.nil?
+        if result.nil?
+          Legion::Logging.debug "Vault kv get: #{path} returned nil" if defined?(Legion::Logging)
+          return nil
+        end
 
+        Legion::Logging.debug "Vault kv get: #{path} returned keys=#{result.data&.keys&.inspect}" if defined?(Legion::Logging)
         result.data
       rescue StandardError => e
-        Legion::Logging.warn "Vault kv get failed at #{path}: #{e.message}" if defined?(Legion::Logging)
+        Legion::Logging.warn "Vault kv get failed at #{path}: #{e.class}=#{e.message}" if defined?(Legion::Logging)
         raise
       end
 
@@ -159,6 +176,29 @@ module Legion
           ::Vault.logical
         end
       end
+
+      def log_read_context(full_path)
+        return unless defined?(Legion::Logging)
+
+        namespace = if respond_to?(:connected_clusters) && connected_clusters.any?
+                      client = vault_client
+                      client.respond_to?(:namespace) ? client.namespace : 'n/a'
+                    else
+                      'n/a (global client)'
+                    end
+        Legion::Logging.debug "Vault read: path=#{full_path}, namespace=#{namespace}"
+      end
+
+      def unwrap_kv_v2(data, full_path)
+        return data unless data.is_a?(Hash) && data.key?(:data) && data[:data].is_a?(Hash) && data.key?(:metadata)
+
+        log_vault_debug("Vault read: #{full_path} detected KV v2 envelope, unwrapping :data key")
+        data[:data]
+      end
+
+      def log_vault_debug(message)
+        Legion::Logging.debug(message) if defined?(Legion::Logging)
+      end
     end
   end
 end

data/lib/legion/crypt/vault_cluster.rb

@@ -40,8 +40,10 @@ module Legion
       end
 
       def connect_all_clusters
+        log_vault_debug("connect_all_clusters: #{clusters.size} cluster(s) configured")
         results = {}
         clusters.each do |name, config|
+          log_vault_debug("connect_all_clusters: #{name} (auth_method=#{config[:auth_method].inspect})")
           case config[:auth_method]&.to_s
           when 'kerberos'
             results[name] = connect_kerberos_cluster(name, config)
@@ -61,7 +63,9 @@ module Legion
           log_vault_error(name, e)
         end
 
-        mark_vault_connected if results.any? { |_, v| v }
+        connected = results.select { |_, v| v }
+        log_vault_debug("connect_all_clusters: #{connected.size}/#{results.size} connected")
+        mark_vault_connected if connected.any?
         results
       end
 
@@ -82,8 +86,10 @@ module Legion
       def build_vault_client(config)
         return nil unless config.is_a?(Hash)
 
+        addr = "#{config[:protocol]}://#{config[:address]}:#{config[:port]}"
+        log_vault_debug("build_vault_client: address=#{addr}")
         client = ::Vault::Client.new(
-          address: "#{config[:protocol]}://#{config[:address]}:#{config[:port]}",
+          address: addr,
           token:   config[:token]
         )
         namespace =
@@ -94,6 +100,7 @@ module Legion
             crypt_settings.respond_to?(:dig) ? crypt_settings.dig(:vault, :vault_namespace) : nil
           end
         client.namespace = namespace if namespace
+        log_vault_debug("build_vault_client: namespace=#{namespace.inspect}")
         client
       end
 
@@ -108,6 +115,9 @@ module Legion
       def connect_kerberos_cluster(name, config)
         krb_config = config[:kerberos] || {}
         spn = krb_config[:service_principal]
+        auth_path = krb_config[:auth_path] || Legion::Crypt::KerberosAuth::DEFAULT_AUTH_PATH
+
+        log_vault_debug("connect_kerberos_cluster[#{name}]: SPN=#{spn}, auth_path=#{auth_path}, namespace=#{config[:namespace].inspect}")
 
         unless spn
           log_vault_warn(name, 'Kerberos auth missing service_principal, skipping')
@@ -116,10 +126,13 @@ module Legion
         end
 
         require 'legion/crypt/kerberos_auth'
+        client = vault_client(name)
+        log_vault_debug("connect_kerberos_cluster[#{name}]: client.namespace=#{client.respond_to?(:namespace) ? client.namespace.inspect : 'n/a'}")
+
         result = Legion::Crypt::KerberosAuth.login(
-          vault_client:      vault_client(name),
+          vault_client:      client,
           service_principal: spn,
-          auth_path:         krb_config[:auth_path] || Legion::Crypt::KerberosAuth::DEFAULT_AUTH_PATH
+          auth_path:         auth_path
         )
 
         config[:token] = result[:token]
@@ -127,6 +140,7 @@ module Legion
         config[:renewable] = result[:renewable]
         config[:connected] = true
         vault_client(name).token = result[:token]
+        log_vault_debug("connect_kerberos_cluster[#{name}]: policies=#{result[:policies].inspect}")
         log_cluster_connected(name, config)
         true
       rescue Legion::Crypt::KerberosAuth::GemMissingError => e
@@ -150,6 +164,10 @@ module Legion
           warn("Vault cluster #{name}: #{message}")
         end
       end
+
+      def log_vault_debug(message)
+        Legion::Logging.debug(message) if defined?(Legion::Logging)
+      end
     end
   end
 end

data/lib/legion/crypt/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Crypt
-    VERSION = '1.4.19'
+    VERSION = '1.4.22'
   end
 end

data/lib/legion/crypt.rb

@@ -123,7 +123,13 @@ module Legion
         lease_manager = Legion::Crypt::LeaseManager.instance
         lease_manager.start(leases, vault_client: client)
         lease_manager.start_renewal_thread
-        Legion::Logging.info "LeaseManager: #{leases.size} lease(s) initialized"
+        fetched = lease_manager.fetched_count
+        defined = leases.size
+        if fetched == defined
+          Legion::Logging.info "LeaseManager: #{fetched} lease(s) initialized"
+        else
+          Legion::Logging.warn "LeaseManager: #{fetched}/#{defined} lease(s) initialized (#{defined - fetched} failed)"
+        end
       rescue StandardError => e
         Legion::Logging.warn "LeaseManager startup failed: #{e.message}"
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-crypt
 version: !ruby/object:Gem::Version
-  version: 1.4.19
+  version: 1.4.22
 platform: ruby
 authors:
 - Esity