legion-crypt 1.5.5 → 1.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85275c53d61c6172fcabf74c69df85324c94d828372894e7d29e2c550501fc88
-  data.tar.gz: 61a939f7fb79750ca314840c2c16766e7d325eb956e2d9e3d6196174bde1f0ea
+  metadata.gz: 3b695e8ac3853b730218da5e1b40b9f7bdc9c7fbffbd1ec4eddccd5539fe296a
+  data.tar.gz: 544bf702cdcc9114b7fa0b99c14141fa6f58b37ee9dbde767e953076ffaedb4c
 SHA512:
-  metadata.gz: 3d7d33ed75be9d7263b32e9cb3830bff352dddd68fff8a8f060c26a7856a1962a8be31fa2955cabb76b6c961a7891890fae22b94c001e718b91ecdb5a2df3286
-  data.tar.gz: c6df0c72440d9ac6cb134bbd1498d68f51a582431d974ee42a7084e9077170125047e0d55293623109c8c14562f34b86577482d100e2d82ad06125a09ade17d1
+  metadata.gz: dcf4c2dd40eeb403ec1708be60992abf7970d73e1f084f84cd840c4a1718c70497cee70a6bfe5b3d402852a9289f8498a3afbc23973a557e3f1cca355d2fefbe
+  data.tar.gz: a90c05a4b59d770f8cd0276008e9454e15e966e570ebf0248f8d5bb8fa48c67120c91d357e8b7225d14ec98547c41cc2914c130a65022e416e6739e489d4c526

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [1.5.7] - 2026-04-08
+
+### Fixed
+- `LeaseManager#cache_lease` now stores the `:path` from static lease definitions, enabling `reissue_lease` fallback when `sys.renew` fails or leases hit max_ttl — previously static leases (configured via `crypt.vault.leases`) would silently expire after their TTL with no recovery (fixes #28)
+- `LeaseManager#renew_lease` now logs a warning and falls back to reissue when the path is available, or warns explicitly when no path is available — previously renewal failures for pathless leases were silent
+
+### Added
+- `LeaseManager#trigger_reconnect(name)` — dispatches reconnect to the appropriate service after credential reissue: `:rabbitmq` → `Transport::Connection.force_reconnect`, `:postgresql` → `Data.reconnect`, `:redis` → `Cache.reconnect`; all guarded with `defined?`/`respond_to?` and rescue-safe
+- Comprehensive INFO/WARN logging across the entire lease lifecycle:
+  - INFO on lease fetch attempt, fetch success (with lease_id/ttl/renewable), renewal attempt, renewal success (with new_ttl), reissue attempt, reissue success (with new_lease_id/ttl), approaching expiry detection (with remaining/renewable/has_path), credentials changed during renewal, reconnect triggered, renewal loop start/exit
+  - WARN on non-renewable lease with no reissue path, renewal failure with no reissue path, reissue returning no data, reconnect failure, cannot reissue due to missing path
+
+### Changed
+- `LeaseManager#reissue_lease` now calls `trigger_reconnect(name)` instead of inline `:rabbitmq`-only `force_reconnect`, extending credential rotation reconnect support to PostgreSQL and Redis
+
+## [1.5.6] - 2026-04-07
+
+### Added
+- `VaultEntity` module (`lib/legion/crypt/vault_entity.rb`) — Phase 7 Vault identity tracking
+  - `ensure_entity(principal_id:, canonical_name:, metadata: {})` — creates or finds a Vault entity for a Legion principal; entity names are prefixed with `legion-` to avoid collision; metadata includes `legion_principal_id`, `legion_canonical_name`, and `managed_by: 'legion'`; returns entity ID string or nil on failure (non-fatal)
+  - `ensure_alias(entity_id:, mount_accessor:, alias_name:)` — creates an entity alias linking an auth method mount to the entity; idempotent (`already exists` HTTPClientError is swallowed); all other `Vault::HTTPClientError` responses log warn and return nil (non-fatal)
+  - `find_by_name(canonical_name)` — looks up a Vault entity by its Legion canonical name via `identity/entity/name/legion-{name}`; returns entity ID or nil
+  - All operations are non-fatal — rescue and log warn on failure; boot/request flow is never blocked by entity tracking errors
+  - Delegates Vault API calls to `LeaseManager.instance.vault_logical` (public delegator) when available; falls back to `::Vault.logical`
+
 ## [1.5.5] - 2026-04-07
 
 ### Added

data/CLAUDE.md

@@ -8,7 +8,7 @@
 Handles encryption, decryption, secrets management, JWT token management, and HashiCorp Vault connectivity for the LegionIO framework. Provides AES-256-CBC message encryption, RSA key pair generation, cluster secret management, JWT issue/verify operations, and Vault token lifecycle management.
 
 **GitHub**: https://github.com/LegionIO/legion-crypt
-**Version**: 1.4.15
+**Version**: 1.5.7
 **License**: Apache-2.0
 
 ## Architecture
@@ -63,6 +63,11 @@ Legion::Crypt (singleton module)
 ├── Tls                # TLS settings (cert/key/CA/verify_peer/Vault PKI)
 ├── Mtls               # mTLS cert issuance (Vault PKI) + CertRotation background thread (50% TTL renewal)
 ├── TokenRenewer       # Background renewal thread: 75% TTL renew, Kerberos re-auth on failure, exponential backoff
+├── Spiffe             # SPIFFE identity support: parse_id, valid_id?, X509Svid, JwtSvid structs; reads security.spiffe settings
+├── Spiffe::IdentityHelpers  # Mixin for SPIFFE identity operations
+├── Spiffe::SvidRotation     # Background SVID renewal at 50% TTL
+├── Spiffe::WorkloadApiClient # gRPC workload API client for SPIRE agent (unix socket)
+├── VaultEntity        # Vault entity/alias lifecycle (ensure_entity, ensure_alias, find_by_name); all non-fatal
 ├── MockVault          # In-memory Vault mock for local development mode
 ├── Settings           # Default crypt config
 └── Version
@@ -132,6 +137,11 @@ Dev dependencies: `legion-logging`, `legion-settings`
 | `lib/legion/crypt/tls.rb` | TLS settings module (cert, key, CA paths, verify_peer, Vault PKI flag) |
 | `lib/legion/crypt/mtls.rb` | mTLS certificate issuance from Vault PKI; `CertRotation` background renewal thread (50% TTL) |
 | `lib/legion/crypt/token_renewer.rb` | Plain Thread renewer: renews at 75% TTL, re-auths via Kerberos on failure, exponential backoff |
+| `lib/legion/crypt/spiffe.rb` | SPIFFE identity: parse/validate SPIFFE IDs, X509Svid/JwtSvid structs, settings helpers |
+| `lib/legion/crypt/spiffe/identity_helpers.rb` | Mixin for SPIFFE identity operations |
+| `lib/legion/crypt/spiffe/svid_rotation.rb` | Background SVID renewal thread (50% TTL) |
+| `lib/legion/crypt/spiffe/workload_api_client.rb` | gRPC workload API client for SPIRE agent |
+| `lib/legion/crypt/vault_entity.rb` | Vault entity/alias lifecycle: `ensure_entity`, `ensure_alias`, `find_by_name`; all operations non-fatal |
 | `lib/legion/crypt/version.rb` | VERSION constant |
 
 ## Role in LegionIO

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.22
+**Version**: 1.5.6
 
 ## Installation
 

data/lib/legion/crypt/jwks_client.rb

@@ -61,6 +61,7 @@ module Legion
           Thread.new do
             fetch_keys(jwks_url)
           rescue StandardError => e
+            handle_exception(e, level: :debug, operation: 'crypt.jwks.prefetch', jwks_url: jwks_url) if respond_to?(:handle_exception)
             log.debug "JWKS prefetch failed for #{jwks_url}: #{e.message}" if respond_to?(:log)
           end
         end
@@ -71,6 +72,7 @@ module Legion
           @refresh_task = Concurrent::TimerTask.new(execution_interval: interval, run_now: false) do
             fetch_keys(jwks_url)
           rescue StandardError => e
+            handle_exception(e, level: :debug, operation: 'crypt.jwks.background_refresh', jwks_url: jwks_url) if respond_to?(:handle_exception)
             log.debug "JWKS background refresh failed: #{e.message}" if respond_to?(:log)
           end
           @refresh_task.execute
@@ -121,7 +123,10 @@ module Legion
 
           response.body
         rescue StandardError => e
-          raise Legion::Crypt::JWT::Error, "failed to fetch JWKS: #{e.message}" unless e.is_a?(Legion::Crypt::JWT::Error)
+          unless e.is_a?(Legion::Crypt::JWT::Error)
+            handle_exception(e, level: :warn, operation: 'crypt.jwks.http_get', url: url) if respond_to?(:handle_exception)
+            raise Legion::Crypt::JWT::Error, "failed to fetch JWKS: #{e.message}"
+          end
 
           raise
         end

data/lib/legion/crypt/lease_manager.rb

@@ -40,6 +40,7 @@ module Legion
           revoke_expired_lease(name)
 
           begin
+            log.info("LeaseManager: fetching lease '#{name}' from #{path}")
             response = logical.read(path)
             unless response
               log.warn("LeaseManager: no data at '#{name}' (#{path}) — path may not exist or role not configured")
@@ -47,8 +48,9 @@ module Legion
             end
 
             log_lease_response(name, response)
-            cache_lease(name, response)
-            log.info("LeaseManager: fetched lease for '#{name}' from #{path}")
+            cache_lease(name, response, path: path)
+            log.info("LeaseManager: fetched lease '#{name}' from #{path} " \
+                     "(lease_id=#{response.lease_id.to_s[0..11]}... ttl=#{response.lease_duration}s renewable=#{response.renewable?})")
           rescue StandardError => e
             handle_exception(e, level: :warn, operation: 'crypt.lease_manager.start', lease_name: name, path: path)
             log.warn("LeaseManager: failed to fetch lease '#{name}' from #{path}: #{e.message}")
@@ -129,14 +131,21 @@ module Legion
 
       def reissue_lease(name)
         lease = @state_mutex.synchronize { @active_leases[name]&.dup }
-        return unless lease && lease[:path]
+        unless lease && lease[:path]
+          log.warn("LeaseManager: cannot reissue lease '#{name}' — no path stored for re-read")
+          return
+        end
 
+        log.info("LeaseManager: reissuing lease '#{name}' from #{lease[:path]}")
         response = logical.read(lease[:path])
-        return unless response&.data
+        unless response&.data
+          log.warn("LeaseManager: reissue for '#{name}' returned no data from #{lease[:path]}")
+          return
+        end
 
-        @state_mutex.synchronize do
+        updated = @state_mutex.synchronize do
           active_lease = @active_leases[name]
-          next unless active_lease
+          next false unless active_lease
 
           @lease_cache[name] = response.data
           active_lease.merge!(
@@ -146,13 +155,18 @@ module Legion
             fetched_at:     Time.now,
             renewable:      response.renewable?
           )
+          true
+        end
+        unless updated
+          log.warn("LeaseManager: reissue for '#{name}' skipped — lease was removed during reissue (likely shutdown)")
+          return
         end
-        push_to_settings(name)
-
-        return unless name == :rabbitmq && defined?(Legion::Transport::Connection)
 
-        Legion::Transport::Connection.force_reconnect
-        log.info("LeaseManager: reissued lease '#{name}' and triggered transport reconnect")
+        lease_id_preview = response.lease_id.to_s[0..11]
+        log.info("LeaseManager: reissued lease '#{name}' " \
+                 "(new_lease_id=#{lease_id_preview}... ttl=#{response.lease_duration}s)")
+        push_to_settings(name)
+        trigger_reconnect(name)
       rescue StandardError => e
         handle_exception(e, level: :warn, operation: 'crypt.lease_manager.reissue_lease', lease_name: name)
         log.warn("LeaseManager: failed to reissue lease '#{name}': #{e.message}")
@@ -227,7 +241,7 @@ module Legion
         @at_exit_registered = true
       end
 
-      def cache_lease(name, response)
+      def cache_lease(name, response, path: nil)
         @state_mutex.synchronize do
           @lease_cache[name] = response.data || {}
           @active_leases[name] = {
@@ -235,7 +249,8 @@ module Legion
             lease_duration: response.lease_duration,
             renewable:      response.renewable?,
             expires_at:     Time.now + (response.lease_duration || 0),
-            fetched_at:     Time.now
+            fetched_at:     Time.now,
+            path:           path
           }
         end
       end
@@ -286,13 +301,15 @@ module Legion
       end
 
       def renewal_loop
+        log.info 'LeaseManager: renewal loop started'
         while running?
           interruptible_sleep(RENEWAL_CHECK_INTERVAL)
           renew_approaching_leases if running?
         end
+        log.info 'LeaseManager: renewal loop exiting'
       rescue StandardError => e
         handle_exception(e, level: :error, operation: 'crypt.lease_manager.renewal_loop')
-        log.error("LeaseManager: renewal loop error: #{e.message}")
+        log.error("LeaseManager: renewal loop error: #{e.message} — restarting")
         retry if running?
       end
 
@@ -303,36 +320,71 @@ module Legion
           next unless lease
           next unless approaching_expiry?(lease)
 
+          remaining = lease[:expires_at] ? (lease[:expires_at] - Time.now).round(1) : 'unknown'
+          log.debug("LeaseManager: lease '#{name}' approaching expiry " \
+                    "(remaining=#{remaining}s renewable=#{lease[:renewable]} has_path=#{!lease[:path].nil?})")
+
           if lease[:renewable]
             renew_lease(name, lease)
           elsif lease[:path]
-            log.info("LeaseManager: lease '#{name}' is non-renewable and approaching expiry — re-issuing")
+            log.info("LeaseManager: lease '#{name}' is non-renewable — re-issuing from #{lease[:path]}")
             reissue_lease(name)
+          else
+            log.warn("LeaseManager: lease '#{name}' is non-renewable and has no path for reissue — " \
+                     "will expire at #{lease[:expires_at]}")
           end
         end
       end
 
       def renew_lease(name, lease)
-        response = sys.renew(lease[:lease_id])
+        lease_id = lease[:lease_id].to_s
+        if lease_id.empty?
+          log.warn("LeaseManager: lease '#{name}' is renewable but has no lease_id")
+          if lease[:path]
+            log.warn("LeaseManager: falling back to reissue for '#{name}' from #{lease[:path]}")
+            reissue_lease(name)
+          else
+            log.warn("LeaseManager: lease '#{name}' renewal failed and no path available for reissue — " \
+                     "lease will expire at #{lease[:expires_at]}")
+          end
+          return
+        end
+
+        log.info("LeaseManager: renewing lease '#{name}' (lease_id=#{lease_id[0..11]}...)")
+        response = sys.renew(lease_id)
+        new_ttl = response.respond_to?(:lease_duration) ? response.lease_duration : nil
         @state_mutex.synchronize do
           current_lease = @active_leases[name]
           next unless current_lease
 
-          current_lease[:lease_duration] = response.lease_duration if response.respond_to?(:lease_duration)
+          if new_ttl
+            current_lease[:lease_duration] = new_ttl
+            current_lease[:expires_at] = Time.now + new_ttl
+          end
           current_lease[:renewable] = response.renewable? if response.respond_to?(:renewable?)
-          current_lease[:expires_at] = Time.now + (response.lease_duration || 0)
         end
-        log.info("LeaseManager: renewed lease '#{name}'")
+        if new_ttl
+          log.info("LeaseManager: renewed lease '#{name}' (new_ttl=#{new_ttl}s)")
+        else
+          log.warn("LeaseManager: renewed lease '#{name}' but Vault returned no lease_duration — keeping previous TTL")
+        end
 
         cached_data = @state_mutex.synchronize { @lease_cache[name] }
         if response.data && response.data != cached_data
           @state_mutex.synchronize { @lease_cache[name] = response.data }
           push_to_settings(name)
+          log.info("LeaseManager: lease '#{name}' credentials changed during renewal — settings updated")
         end
       rescue StandardError => e
         handle_exception(e, level: :warn, operation: 'crypt.lease_manager.renew_lease', lease_name: name)
         log.warn("LeaseManager: failed to renew lease '#{name}': #{e.message}")
-        reissue_lease(name) if lease[:path]
+        if lease[:path]
+          log.warn("LeaseManager: falling back to reissue for '#{name}' from #{lease[:path]}")
+          reissue_lease(name)
+        else
+          log.warn("LeaseManager: lease '#{name}' renewal failed and no path available for reissue — " \
+                   "lease will expire at #{lease[:expires_at]}")
+        end
       end
 
       def lease_valid?(name)
@@ -390,6 +442,30 @@ module Legion
         log.warn("LeaseManager: failed to write setting at #{path.join('.')}: #{e.message}")
       end
 
+      def trigger_reconnect(name)
+        name = name.to_sym if name.respond_to?(:to_sym)
+        case name
+        when :rabbitmq
+          return unless defined?(Legion::Transport::Connection)
+
+          Legion::Transport::Connection.force_reconnect
+          log.info("LeaseManager: triggered transport reconnect after '#{name}' reissue")
+        when :postgresql
+          return unless defined?(Legion::Data) && Legion::Data.respond_to?(:reconnect)
+
+          Legion::Data.reconnect
+          log.info("LeaseManager: triggered data reconnect after '#{name}' reissue")
+        when :redis
+          return unless defined?(Legion::Cache) && Legion::Cache.respond_to?(:reconnect)
+
+          Legion::Cache.reconnect
+          log.info("LeaseManager: triggered cache reconnect after '#{name}' reissue")
+        end
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.lease_manager.trigger_reconnect', lease_name: name)
+        log.warn("LeaseManager: reconnect for '#{name}' failed: #{e.message}")
+      end
+
       def running?
         @state_mutex.synchronize { @running }
       end

data/lib/legion/crypt/vault_cluster.rb

@@ -81,6 +81,7 @@ module Legion
       rescue ::Vault::HTTPError => e
         return true if e.message =~ /\b(429|472|473)\b/
 
+        handle_exception(e, level: :warn, operation: 'crypt.vault_cluster.cluster_healthy')
         raise
       end
 

data/lib/legion/crypt/vault_entity.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'legion/logging/helper'
+
+module Legion
+  module Crypt
+    module VaultEntity
+      extend Legion::Logging::Helper
+
+      # Create or lookup a Vault entity for a Legion principal.
+      # Returns the Vault entity ID string, or nil on failure.
+      def self.ensure_entity(principal_id:, canonical_name:, metadata: {})
+        existing = find_by_name(canonical_name)
+        return existing if existing
+
+        response = vault_logical.write(
+          'identity/entity',
+          name:     "legion-#{canonical_name}",
+          metadata: metadata.merge(
+            legion_principal_id:   principal_id,
+            legion_canonical_name: canonical_name,
+            managed_by:            'legion'
+          )
+        )
+        extract_id(response)
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.vault_entity.ensure_entity', canonical_name: canonical_name)
+        nil
+      end
+
+      # Create an alias linking an auth method mount to the entity.
+      # Idempotent — swallows "already exists" 4xx errors.
+      def self.ensure_alias(entity_id:, mount_accessor:, alias_name:)
+        vault_logical.write(
+          'identity/entity-alias',
+          name:           alias_name,
+          canonical_id:   entity_id,
+          mount_accessor: mount_accessor
+        )
+      rescue ::Vault::HTTPClientError => e
+        if e.message.include?('already exists')
+          log.debug 'Vault entity alias already exists (idempotent)'
+        else
+          handle_exception(e, level: :warn, operation: 'crypt.vault_entity.ensure_alias', alias_name: alias_name)
+        end
+        nil
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.vault_entity.ensure_alias', alias_name: alias_name)
+        nil
+      end
+
+      # Look up a Vault entity by its Legion canonical name.
+      # Returns the Vault entity ID string, or nil if not found.
+      def self.find_by_name(canonical_name)
+        response = vault_logical.read("identity/entity/name/legion-#{canonical_name}")
+        extract_id(response)
+      rescue ::Vault::HTTPClientError => e
+        unless e.message.match?(/not found|does not exist|404/i)
+          handle_exception(e, level: :warn, operation: 'crypt.vault_entity.find_by_name', canonical_name: canonical_name)
+        end
+        nil
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.vault_entity.find_by_name', canonical_name: canonical_name)
+        nil
+      end
+
+      # ---------------------------------------------------------------------------
+      # Private helpers
+      # ---------------------------------------------------------------------------
+
+      def self.vault_logical
+        if defined?(Legion::Crypt::LeaseManager)
+          Legion::Crypt::LeaseManager.instance.vault_logical
+        else
+          ::Vault.logical
+        end
+      end
+      private_class_method :vault_logical
+
+      # Extract entity ID from a Vault response, supporting both symbol and
+      # string keys (Vault SDK may return either depending on version/transport).
+      def self.extract_id(response)
+        data = response&.data
+        return nil unless data
+
+        data[:id] || data['id']
+      end
+      private_class_method :extract_id
+    end
+  end
+end

data/lib/legion/crypt/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Crypt
-    VERSION = '1.5.5'
+    VERSION = '1.5.7'
   end
 end

data/lib/legion/crypt.rb

@@ -138,6 +138,7 @@ module Legion
 
         log.info "Bootstrap RMQ credentials acquired (lease: #{@bootstrap_lease_id[0..7]}...)"
       rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.fetch_bootstrap_rmq_creds')
         log.warn "Bootstrap RMQ credential fetch failed: #{e.message}"
       end
 
@@ -188,6 +189,7 @@ module Legion
         @bootstrap_lease_id      = nil
         @bootstrap_lease_expires = nil
       rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.revoke_bootstrap_lease')
         log.warn "Bootstrap lease revocation failed: #{e.message} — lease will expire naturally"
         @bootstrap_lease_id      = nil
         @bootstrap_lease_expires = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-crypt
 version: !ruby/object:Gem::Version
-  version: 1.5.5
+  version: 1.5.7
 platform: ruby
 authors:
 - Esity
@@ -127,6 +127,7 @@ files:
 - lib/legion/crypt/token_renewer.rb
 - lib/legion/crypt/vault.rb
 - lib/legion/crypt/vault_cluster.rb
+- lib/legion/crypt/vault_entity.rb
 - lib/legion/crypt/vault_jwt_auth.rb
 - lib/legion/crypt/vault_kerberos_auth.rb
 - lib/legion/crypt/vault_renewer.rb