lex-node 0.3.6 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc51c7fec2b526f23237c3c8da1c8457f7b10250ad7606a3d519049675025cc5
-  data.tar.gz: a0f8d664fdd16a3d16d64a948e3dfe2e8c27935251f1be5ffeef3bac21042220
+  metadata.gz: 7d243dbcf948208a7274558621a0653a8f35b209398a992dfe2cfa658af21c61
+  data.tar.gz: bfa04d660f833939a44d155703e5c6038e71d03bc3c511b4f3a0d66d1988a056
 SHA512:
-  metadata.gz: fd71f5b8d3152d625af005aef5add980d90548d6299bf7f6afd93b69585941b69c37b29ecc882d9325a0075d0fc60b744c9080305e2375350714f3a8cfcb52ba
-  data.tar.gz: c127f5a0b891e70df65b4639588a628596c8207ec31a21529bee8f39117c4cbf36b4d202d27b2619224e815035291bd8c8b81015f1a369071ff1041a8339d770
+  metadata.gz: 64d3c06f36f78d07eb13ea50344e53cdff8526d84aa66652d349186b8f87965997a406714a0caccc731aa6cdd04a4a6f8caac821fd8ca87f5357ef090b0ae872
+  data.tar.gz: d1e66f3a081e57b5430b9f3faa9a89f420ba479f89444197a176e6f2b52ff96d5a90856e312e2b3b74f35f98c887c24d502c4e2a9edf954b07641dd4c67579e4

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.3.8] - 2026-04-25
+
+### Added
+- Configurable cluster-control payload signing via `extensions.node.cluster_control.auth.mode` (`auto`, `required`, `disabled`), with timestamp freshness and nonce format validation when signing is active.
+
+### Changed
+- `ClusterControl` queues now read durability and retention settings from `extensions.node.cluster_control.queue`; defaults remain durable and non-auto-delete so per-node commands survive node restarts.
+- Beat no longer runs immediately at actor construction, avoiding startup reconciliation before extension boot completes.
+- `update_gem` now installs through `Legion::Extensions::GemSource` and calls extension-scoped reload instead of full daemon reload.
+
+## [0.3.7] - 2026-03-31
+
+### Fixed
+- `ClusterControl` exchange now inherits from `Legion::Transport::Exchange` instead of being a bare PORO with constants, fixing `NOT_FOUND` error during autobuild queue binding
+
 ## [0.3.6] - 2026-03-31
 
 ### Added

data/README.md

@@ -68,6 +68,37 @@ Each node periodically calls `beat` to broadcast its presence. On startup, nodes
 
 Dynamic config changes (`update_settings`) and gem upgrades (`update_gem`) can be pushed to individual nodes or broadcast to all nodes at runtime. Both operations publish an `UpdateResult` message to `node.<name>.update_result` so the outcome can be observed cluster-wide.
 
+### Cluster Control Settings
+
+Cluster-control broadcasts are configurable under `extensions.node.cluster_control`. By default, auth mode is `auto`: messages are signed and verified when a shared secret is configured, and unsigned messages are allowed when no secret exists for simpler local or homelab deployments.
+
+```json
+{
+  "extensions": {
+    "node": {
+      "cluster_control": {
+        "auth": {
+          "mode": "auto",
+          "timestamp_skew_seconds": 300,
+          "nonce_bytes": 16
+        },
+        "queue": {
+          "durable": true,
+          "exclusive": false,
+          "auto_delete": false,
+          "queue_type": "classic",
+          "expires_ms": 604800000,
+          "message_ttl_ms": 86400000,
+          "max_length": 1000
+        }
+      }
+    }
+  }
+}
+```
+
+Set `auth.mode` to `required` to force HMAC signatures, or `disabled` to run without cluster-control signatures even when a shared secret is present.
+
 ## Transport
 
 - **Exchange**: `node` (topic exchange)

data/lib/legion/extensions/node/actors/beat.rb

@@ -22,7 +22,7 @@ module Legion
           end
 
           def run_now?
-            true
+            false
           end
 
           def time

data/lib/legion/extensions/node/actors/cluster_control.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/node/control_auth'
+
 module Legion
   module Extensions
     module Node
@@ -28,6 +30,11 @@ module Legion
           def generate_task?
             false
           end
+
+          def process_message(message, metadata, delivery_info)
+            verified_message = Legion::Extensions::Node::ControlAuth.verify!(message)
+            super(verified_message, metadata, delivery_info)
+          end
         end
       end
     end

data/lib/legion/extensions/node/config.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Node
+      module Config
+        DEFAULT_SETTINGS = {
+          cluster_control: {
+            auth:  {
+              mode:                   'auto',
+              timestamp_skew_seconds: 300,
+              nonce_bytes:            16
+            },
+            queue: {
+              durable:        true,
+              exclusive:      false,
+              auto_delete:    false,
+              queue_type:     'classic',
+              expires_ms:     604_800_000,
+              message_ttl_ms: 86_400_000,
+              max_length:     1000
+            }
+          }
+        }.freeze
+
+        module_function
+
+        def default_settings
+          deep_dup(DEFAULT_SETTINGS)
+        end
+
+        def cluster_control
+          deep_merge(default_settings[:cluster_control], extension_settings[:cluster_control] || {})
+        end
+
+        def control_auth
+          cluster_control[:auth] || {}
+        end
+
+        def control_queue
+          cluster_control[:queue] || {}
+        end
+
+        def extension_settings
+          return {} unless defined?(Legion::Settings) && Legion::Settings.respond_to?(:dig)
+
+          settings = Legion::Settings.dig(:extensions, :node)
+          settings.is_a?(Hash) ? symbolize_keys(settings) : {}
+        rescue StandardError => e
+          log.debug("node settings lookup failed: #{e.message}")
+          {}
+        end
+
+        def deep_merge(base, override)
+          base_hash = symbolize_keys(base)
+          override_hash = symbolize_keys(override)
+          base_hash.merge(override_hash) do |_key, old_value, new_value|
+            old_value.is_a?(Hash) && new_value.is_a?(Hash) ? deep_merge(old_value, new_value) : new_value
+          end
+        end
+
+        def deep_dup(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(key, val), result| result[key] = deep_dup(val) }
+          when Array
+            value.map { |item| deep_dup(item) }
+          else
+            value
+          end
+        end
+
+        def symbolize_keys(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(key, val), result| result[key.to_sym] = symbolize_keys(val) }
+          when Array
+            value.map { |item| symbolize_keys(item) }
+          else
+            value
+          end
+        end
+
+        def log
+          Legion::Logging.respond_to?(:logger) ? Legion::Logging.logger : Legion::Logging
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/node/control_auth.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+require 'json'
+require 'legion/extensions/node/config'
+
+module Legion
+  module Extensions
+    module Node
+      module ControlAuth
+        AUTH_MODES = %w[auto required disabled].freeze
+
+        class UnauthorizedControlMessage < StandardError; end
+
+        module_function
+
+        def sign(payload)
+          normalized = deep_symbolize(payload).dup
+          return normalized unless sign_control_messages?
+
+          control = {
+            sender:    node_name,
+            timestamp: Time.now.utc.to_i,
+            nonce:     SecureRandom.hex(nonce_bytes)
+          }
+          normalized[:control] = control.merge(signature: signature_for(normalized.merge(control: control)))
+          normalized
+        end
+
+        def verify!(payload)
+          normalized = deep_symbolize(payload)
+          raise UnauthorizedControlMessage, 'missing control signature' unless normalized.is_a?(Hash)
+          return normalized unless verify_control_messages?
+
+          control = normalized[:control]
+          raise UnauthorizedControlMessage, 'missing control signature' unless control.is_a?(Hash)
+
+          signature = control[:signature].to_s
+          raise UnauthorizedControlMessage, 'missing control signature' if signature.empty?
+          raise UnauthorizedControlMessage, 'stale control message' unless fresh_timestamp?(control[:timestamp])
+          raise UnauthorizedControlMessage, 'invalid control nonce' unless valid_nonce?(control[:nonce])
+
+          unsigned_control = control.dup
+          unsigned_control.delete(:signature)
+          expected = signature_for(normalized.merge(control: unsigned_control))
+          raise UnauthorizedControlMessage, 'invalid control signature' unless secure_compare(signature, expected)
+
+          normalized
+        end
+
+        def sign_control_messages?
+          return false if auth_disabled?
+          return true if auth_required?
+
+          !secret.to_s.empty?
+        end
+
+        def verify_control_messages?
+          return false if auth_disabled?
+          return true if auth_required?
+
+          !secret.to_s.empty?
+        end
+
+        def auth_mode
+          configured = auth_settings[:mode] || auth_settings[:enabled]
+          mode = case configured
+                 when true then 'required'
+                 when false then 'disabled'
+                 else configured.to_s
+                 end
+          AUTH_MODES.include?(mode) ? mode : 'auto'
+        end
+
+        def auth_required?
+          auth_mode == 'required'
+        end
+
+        def auth_disabled?
+          auth_mode == 'disabled'
+        end
+
+        def auth_settings
+          Legion::Extensions::Node::Config.control_auth
+        end
+
+        def secret
+          configured_secret || ENV.fetch('LEGION_NODE_CONTROL_SECRET', nil)
+        end
+
+        def configured_secret
+          if defined?(Legion::Settings) && Legion::Settings.respond_to?(:dig)
+            auth_settings[:secret] ||
+              Legion::Settings.dig(:cluster, :control_secret) ||
+              Legion::Settings.dig(:crypt, :cluster_secret)
+          end
+        rescue StandardError => e
+          log.debug("control secret lookup failed: #{e.message}")
+          nil
+        end
+
+        def signature_for(payload)
+          value = secret
+          raise UnauthorizedControlMessage, 'cluster control secret is not configured' if value.to_s.empty?
+
+          OpenSSL::HMAC.hexdigest('SHA256', value.to_s, canonical_json(payload))
+        end
+
+        def canonical_json(value)
+          ::JSON.generate(canonicalize(value))
+        end
+
+        def canonicalize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, val), result|
+              result[key.to_s] = canonicalize(val)
+            end.sort.to_h
+          when Array
+            value.map { |item| canonicalize(item) }
+          else
+            value
+          end
+        end
+
+        def deep_symbolize(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, val), result|
+              result[key.to_sym] = deep_symbolize(val)
+            end
+          when Array
+            value.map { |item| deep_symbolize(item) }
+          else
+            value
+          end
+        end
+
+        def fresh_timestamp?(timestamp)
+          ts = Integer(timestamp)
+          (Time.now.utc.to_i - ts).abs <= timestamp_skew_seconds
+        rescue ArgumentError, TypeError => e
+          log.debug("control timestamp validation failed: #{e.message}")
+          false
+        end
+
+        def timestamp_skew_seconds
+          Integer(auth_settings[:timestamp_skew_seconds])
+        rescue ArgumentError, TypeError => e
+          log.debug("control timestamp skew setting invalid: #{e.message}")
+          300
+        end
+
+        def nonce_bytes
+          bytes = Integer(auth_settings[:nonce_bytes])
+          bytes.positive? ? bytes : 16
+        rescue ArgumentError, TypeError => e
+          log.debug("control nonce byte setting invalid: #{e.message}")
+          16
+        end
+
+        def valid_nonce?(nonce)
+          nonce.to_s.match?(/\A[0-9a-f]{#{nonce_bytes * 2}}\z/i)
+        end
+
+        def secure_compare(left, right)
+          return false unless left.bytesize == right.bytesize
+
+          left.bytes.zip(right.bytes).reduce(0) { |acc, (a, b)| acc | (a ^ b) }.zero?
+        end
+
+        def node_name
+          (Legion::Settings[:client]&.fetch(:name, nil) if defined?(Legion::Settings)) || 'unknown'
+        rescue StandardError => e
+          log.debug("node name lookup failed: #{e.message}")
+          'unknown'
+        end
+
+        def log
+          Legion::Logging.respond_to?(:logger) ? Legion::Logging.logger : Legion::Logging
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/node/runners/node.rb

@@ -28,8 +28,10 @@ module Legion
             gem_name = "lex-#{name}"
             log.debug "update_gem: installing #{gem_name} #{version || 'latest'}"
 
-            Gem.install(gem_name, version)
-            Legion.reload if reload
+            install_result = install_extension_gem(gem_name, version)
+            raise Gem::InstallError, install_result[:output].to_s unless install_result[:success]
+
+            reload_extension(gem_name) if reload
 
             publish_update_result(action: 'update_gem', status: 'success', detail: "#{gem_name} #{version || 'latest'}")
           rescue StandardError => e
@@ -146,6 +148,20 @@ module Legion
 
           private
 
+          def install_extension_gem(gem_name, version)
+            require 'legion/extensions/gem_source' unless defined?(Legion::Extensions::GemSource) # rubocop:disable Legion/HelperMigration/RequireDefinedGuard
+
+            Legion::Extensions::GemSource.install_gem(gem_name, version: version)
+          rescue LoadError => e
+            { success: false, output: "GemSource unavailable: #{e.message}" }
+          end
+
+          def reload_extension(gem_name)
+            raise 'extension-scoped reload is unavailable' unless defined?(Legion::Extensions) && Legion::Extensions.respond_to?(:reload_extension)
+
+            Legion::Extensions.reload_extension(gem_name)
+          end
+
           def publish_update_result(action:, status:, detail: nil, error: nil)
             Legion::Extensions::Node::Transport::Messages::UpdateResult.new(
               action:    action,

data/lib/legion/extensions/node/transport/exchanges/cluster_control.rb

@@ -5,10 +5,14 @@ module Legion
     module Node
       module Transport
         module Exchanges
-          class ClusterControl
-            EXCHANGE_NAME = 'legion.cluster.control'
-            EXCHANGE_TYPE = :topic
-            EXCHANGE_OPTIONS = { durable: true }.freeze
+          class ClusterControl < Legion::Transport::Exchange
+            def exchange_name
+              'legion.cluster.control'
+            end
+
+            def default_type
+              'topic'
+            end
           end
         end
       end

data/lib/legion/extensions/node/transport/messages/cluster_killswitch.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/node/control_auth'
+
 module Legion
   module Extensions
     module Node
@@ -25,11 +27,11 @@ module Legion
             end
 
             def message
-              {
+              Legion::Extensions::Node::ControlAuth.sign(
                 function: 'update_settings',
                 settings: { extensions: { blocked: [@options[:extension]] } },
                 restart:  true
-              }
+              )
             end
 
             def validate

data/lib/legion/extensions/node/transport/messages/cluster_settings.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/node/control_auth'
+
 module Legion
   module Extensions
     module Node
@@ -23,11 +25,11 @@ module Legion
             end
 
             def message
-              {
+              Legion::Extensions::Node::ControlAuth.sign(
                 function: 'update_settings',
                 settings: @options[:settings],
                 restart:  @options.fetch(:restart, false)
-              }
+              )
             end
 
             def validate

data/lib/legion/extensions/node/transport/queues/cluster_control.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/node/config'
+
 module Legion
   module Extensions
     module Node
@@ -11,8 +13,36 @@ module Legion
             end
 
             def queue_options
-              { durable: false, exclusive: false, auto_delete: true,
-                arguments: { 'x-queue-type': 'classic' } }
+              options = Legion::Extensions::Node::Config.control_queue
+              { durable:     truthy?(options[:durable], default: true),
+                exclusive:   truthy?(options[:exclusive], default: false),
+                auto_delete: truthy?(options[:auto_delete], default: false),
+                arguments:   queue_arguments(options) }
+            end
+
+            private
+
+            def queue_arguments(options)
+              {
+                'x-queue-type':  options[:queue_type],
+                'x-expires':     positive_integer(options[:expires_ms]),
+                'x-message-ttl': positive_integer(options[:message_ttl_ms]),
+                'x-max-length':  positive_integer(options[:max_length])
+              }.compact
+            end
+
+            def positive_integer(value)
+              return value if value.is_a?(Integer) && value.positive?
+              return nil unless value.to_s.match?(/\A\d+\z/)
+
+              parsed = value.to_i
+              parsed.positive? ? parsed : nil
+            end
+
+            def truthy?(value, default:)
+              return default if value.nil?
+
+              value == true || value.to_s == 'true'
             end
           end
         end

data/lib/legion/extensions/node/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Node
-      VERSION = '0.3.6'
+      VERSION = '0.3.8'
     end
   end
 end

data/lib/legion/extensions/node.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/node/version'
+require 'legion/extensions/node/config'
 require 'legion/extensions/node/helpers/rabbitmq'
 
 module Legion
   module Extensions
     module Node
       extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core, false
+
+      def self.default_settings
+        Config.default_settings
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-node
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.8
 platform: ruby
 authors:
 - Esity
@@ -150,6 +150,8 @@ files:
 - lib/legion/extensions/node/actors/push_key.rb
 - lib/legion/extensions/node/actors/vault.rb
 - lib/legion/extensions/node/actors/vault_token_request.rb
+- lib/legion/extensions/node/config.rb
+- lib/legion/extensions/node/control_auth.rb
 - lib/legion/extensions/node/data_test/migrations/001_nodes_table.rb
 - lib/legion/extensions/node/data_test/migrations/002_node_history_table.rb
 - lib/legion/extensions/node/data_test/migrations/003_legion_version_colume.rb