shared_broker 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fef9571ebd7987fe360d47b8a4374206808487afc3b641b19cb19c6dbfaf85f
-  data.tar.gz: 98fc3d5712273e6d426ac380e5ebd3ff4c9cd6319a1eb00b333ea25cc977cb0f
+  metadata.gz: 24d5ac30bc2bef8c5fd99edbcb8e7e986fa8005fde7cfdb39bfb4f3c6010efa8
+  data.tar.gz: d66d983238edb492bddf145c48866ce83a55b88bf6806472910bdafdbbd418ec
 SHA512:
-  metadata.gz: b6d52305cbfe8cd4e72d9e5bcbd84cc8bbda1c5c738a43e2727586e82f88bbe01d9e060d31ee28443c0b73172b4206ba33fd8640be394e6fba6b9b190f808a44
-  data.tar.gz: fdf993c33a31f8364aa613123159aebbeeae8ebfdd4f5548d6f1eb7210b318e0cc81f660e7ab28d4bc998868386c63086fbcc793d0cfe3ade14ffae82f8afd58
+  metadata.gz: c25d32bc67d7c28427c533b1f3e23b048a7513740f0e8a51e067f5f5d861b761a3189b7d84d06b977400b21bf022c003c50d4515e46cfdc6cee064d36acbdb38
+  data.tar.gz: 1ab4165d6750a4f1d28f3ce67c070d58135d10c793b4eac944ba257b8b01f3dcd0665e36018aa0c32b27076439297e6e8ee0b789f5b943fa2820ef9472d2f09f

data/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-06-16
+
+### Added
+- **Encryption Key Rotation & Granularity**: Introduced flexible topic-based encryption keys and multi-version key rotation.
+- `SharedBroker::KeyProvider::Registry` to register multiple keys by key ID and route active keys based on topic glob patterns.
+- `SharedBroker::KeyProvider::Static` for seamless backward compatibility with single global encryption keys.
+- Automatic versioning of encrypted payloads with `_key_id` metadata, enabling decrypting historical messages using rotated keys.
+
 ## [1.5.0] - 2026-06-10
 
 ### Added

data/README.md

@@ -160,6 +160,41 @@ HYBRID_BROKER = SharedBroker::Client.new(
 )
 ```
 
+#### E. Encryption Key Rotation & Granularity
+
+If your system requires encrypting payloads with different keys based on the topic (e.g., highly sensitive financial data vs. general notifications) or rotating keys without breaking the decryption of historical messages in queues, you can configure a Key Provider Registry:
+
+```ruby
+# 1. Initialize Registry with a map of historical/current keys and active key mappings
+key_registry = SharedBroker::KeyProvider::Registry.new(
+  keys: {
+    "v1"            => "a" * 32, # historical key
+    "v2"            => "b" * 32, # current general key
+    "finance_key_1" => "c" * 32  # current finance key
+  },
+  active_keys: {
+    # Topic-specific key mapping using glob patterns
+    "payment.*" => "finance_key_1",
+    # Fallback key mapping for all other topics
+    "*"         => "v2"
+  }
+)
+
+# 2. Register key provider globally or pass it to Client initialize
+SharedBroker.key_provider = key_registry
+
+# Alternatively, pass it directly to the client
+SPOT_BROKER = SharedBroker::Client.new(
+  adapter: BROKER_ADAPTER,
+  key_provider: key_registry
+)
+```
+
+With a key provider registry configured:
+- **Publishing**: Payloads are encrypted using the active key matching the topic pattern, and a `_key_id` metadata tag is automatically appended to the envelope.
+- **Subscribing**: The gem automatically reads the `_key_id` from the payload envelope and decrypts it using the correct historical key version.
+- **Fallback**: If no `_key_id` is present on a received message (e.g., legacy message), it falls back to the key associated with the topic pattern.
+
 ---
 
 ## Usage

data/lib/shared_broker/cipher.rb

@@ -1,69 +1,98 @@
-# frozen_string_literal: true
-
-require "openssl"
-require "base64"
-require "json"
-
-module SharedBroker
-  module Cipher
-    class DecryptionError < StandardError; end
-
-    ALGORITHM = "aes-256-gcm"
-
-    def self.encrypt(payload_hash, key)
-      return payload_hash unless key
-
-      unless payload_hash.is_a?(Hash)
-        raise ArgumentError, "Expected payload_hash to be a Hash, got #{payload_hash.class} with value #{payload_hash.inspect}"
-      end
-
-      # We don't want to encrypt correlation ID or special metadata keys if we want the broker to read them,
-      # but we want to encrypt the actual payload data.
-      # Let's extract metadata starting with underscore and encrypt the rest.
-      metadata = payload_hash.select { |k, _| k.to_s.start_with?("_") }
-      data_to_encrypt = payload_hash.reject { |k, _| k.to_s.start_with?("_") }
-
-      cipher = OpenSSL::Cipher.new(ALGORITHM)
-      cipher.encrypt
-      cipher.key = key
-      iv = cipher.random_iv
-
-      encrypted_data = cipher.update(data_to_encrypt.to_json) + cipher.final
-      auth_tag = cipher.auth_tag
-
-      metadata.merge(
-        _encrypted: true,
-        _iv: Base64.strict_encode64(iv),
-        _auth_tag: Base64.strict_encode64(auth_tag),
-        _data: Base64.strict_encode64(encrypted_data)
-      )
-    end
-
-    def self.decrypt(payload_hash, key)
-      return payload_hash unless payload_hash.is_a?(Hash) && payload_hash[:_encrypted]
-      return payload_hash unless key
-
-      cipher = OpenSSL::Cipher.new(ALGORITHM)
-      cipher.decrypt
-      cipher.key = key
-      cipher.iv = Base64.strict_decode64(payload_hash[:_iv])
-      cipher.auth_tag = Base64.strict_decode64(payload_hash[:_auth_tag])
-
-      encrypted_bytes = Base64.strict_decode64(payload_hash[:_data])
-      decrypted_json = cipher.update(encrypted_bytes) + cipher.final
-
-      decrypted_data = JSON.parse(decrypted_json, symbolize_names: true)
-      
-      # Merge back the unencrypted metadata
-      metadata = payload_hash.select { |k, _| k.to_s.start_with?("_") }
-      metadata.delete(:_encrypted)
-      metadata.delete(:_iv)
-      metadata.delete(:_auth_tag)
-      metadata.delete(:_data)
-
-      decrypted_data.merge(metadata)
-    rescue => e
-      raise DecryptionError, "Failed to decrypt payload. Error: #{e.message}. Offending payload: #{payload_hash.inspect}"
-    end
-  end
-end
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module SharedBroker
+  module Cipher
+    class DecryptionError < StandardError; end
+
+    ALGORITHM = "aes-256-gcm"
+
+    def self.encrypt(payload_hash, key_provider_or_key, topic: nil)
+      return payload_hash unless key_provider_or_key
+
+      unless payload_hash.is_a?(Hash)
+        raise ArgumentError, "Expected payload_hash to be a Hash, got #{payload_hash.class} with value #{payload_hash.inspect}"
+      end
+
+      key, key_id = resolve_encryption_key(key_provider_or_key, topic)
+      return payload_hash unless key
+
+      metadata = payload_hash.select { |k, _| k.to_s.start_with?("_") }
+      data_to_encrypt = payload_hash.reject { |k, _| k.to_s.start_with?("_") }
+
+      cipher = OpenSSL::Cipher.new(ALGORITHM)
+      cipher.encrypt
+      cipher.key = key
+      iv = cipher.random_iv
+
+      encrypted_data = cipher.update(data_to_encrypt.to_json) + cipher.final
+      auth_tag = cipher.auth_tag
+
+      envelope = {
+        _encrypted: true,
+        _iv: Base64.strict_encode64(iv),
+        _auth_tag: Base64.strict_encode64(auth_tag),
+        _data: Base64.strict_encode64(encrypted_data)
+      }
+      envelope[:_key_id] = key_id.to_s if key_id
+
+      metadata.merge(envelope)
+    end
+
+    def self.decrypt(payload_hash, key_provider_or_key, topic: nil)
+      return payload_hash unless payload_hash.is_a?(Hash) && payload_hash[:_encrypted]
+      return payload_hash unless key_provider_or_key
+
+      key = resolve_decryption_key(payload_hash, key_provider_or_key, topic)
+      return payload_hash unless key
+
+      cipher = OpenSSL::Cipher.new(ALGORITHM)
+      cipher.decrypt
+      cipher.key = key
+      cipher.iv = Base64.strict_decode64(payload_hash[:_iv])
+      cipher.auth_tag = Base64.strict_decode64(payload_hash[:_auth_tag])
+
+      encrypted_bytes = Base64.strict_decode64(payload_hash[:_data])
+      decrypted_json = cipher.update(encrypted_bytes) + cipher.final
+
+      decrypted_data = JSON.parse(decrypted_json, symbolize_names: true)
+      
+      metadata = payload_hash.select { |k, _| k.to_s.start_with?("_") }
+      clean_envelope_metadata!(metadata)
+
+      decrypted_data.merge(metadata)
+    rescue => e
+      raise DecryptionError, "Failed to decrypt payload. Error: #{e.message}. Offending payload: #{payload_hash.inspect}"
+    end
+
+    private
+
+    def self.resolve_encryption_key(provider_or_key, topic)
+      if provider_or_key.respond_to?(:key_for)
+        [provider_or_key.key_for(topic), provider_or_key.active_key_id_for(topic)]
+      else
+        [provider_or_key, nil]
+      end
+    end
+
+    def self.resolve_decryption_key(payload, provider_or_key, topic)
+      if provider_or_key.respond_to?(:key_for_id)
+        key_id = payload[:_key_id]
+        key_id ? provider_or_key.key_for_id(key_id) : provider_or_key.key_for(topic)
+      else
+        provider_or_key
+      end
+    end
+
+    def self.clean_envelope_metadata!(metadata)
+      metadata.delete(:_encrypted)
+      metadata.delete(:_iv)
+      metadata.delete(:_auth_tag)
+      metadata.delete(:_data)
+      metadata.delete(:_key_id)
+    end
+  end
+end

data/lib/shared_broker/key_provider.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SharedBroker
+  module KeyProvider
+    class KeyNotFoundError < StandardError; end
+
+    # Static key provider for backward compatibility
+    class Static
+      def initialize(key)
+        raise ArgumentError, "Expected key to be a 32-byte String, got #{key.inspect}" unless key.is_a?(String)
+        @key = key
+      end
+
+      def key_for(_topic)
+        @key
+      end
+
+      def key_for_id(_key_id)
+        @key
+      end
+
+      def active_key_id_for(_topic)
+        nil
+      end
+    end
+
+    # Flexible registry for multiple keys and topic-based routing patterns
+    class Registry
+      def initialize(keys: {}, active_keys: {})
+        validate_inputs!(keys, active_keys)
+        @keys = keys.transform_keys(&:to_s)
+        @active_keys = active_keys.transform_keys(&:to_s)
+      end
+
+      def key_for(topic)
+        key_id = active_key_id_for(topic)
+        key_for_id(key_id)
+      end
+
+      def key_for_id(key_id)
+        return nil if key_id.nil?
+        
+        key = @keys[key_id.to_s]
+        return key if key
+
+        raise KeyNotFoundError, "Key ID #{key_id.inspect} not found in registered keys. Available keys: #{@keys.keys.inspect}"
+      end
+
+      def active_key_id_for(topic)
+        topic_str = topic.to_s
+        return @active_keys[topic_str] if @active_keys.key?(topic_str)
+
+        pattern = find_matching_pattern(topic_str)
+        return @active_keys[pattern] if pattern
+
+        fallback_key_id
+      end
+
+      private
+
+      def validate_inputs!(keys, active_keys)
+        unless keys.is_a?(Hash) && active_keys.is_a?(Hash)
+          raise ArgumentError, "Expected keys and active_keys to be Hashes, got keys: #{keys.inspect}, active_keys: #{active_keys.inspect}"
+        end
+      end
+
+      def find_matching_pattern(topic_str)
+        @active_keys.keys.find do |pattern|
+          pattern != "*" && File.fnmatch?(pattern, topic_str)
+        end
+      end
+
+      def fallback_key_id
+        @active_keys["*"] || raise(KeyNotFoundError, "No active key configuration found for fallback '*' pattern")
+      end
+    end
+  end
+end

data/lib/shared_broker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SharedBroker
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/lib/shared_broker.rb

@@ -8,6 +8,7 @@ require_relative "shared_broker/schema_registry/providers/local"
 require_relative "shared_broker/schema_registry/providers/http"
 require_relative "shared_broker/validation"
 require_relative "shared_broker/cipher"
+require_relative "shared_broker/key_provider"
 require_relative "shared_broker/concurrency/semaphore"
 require_relative "shared_broker/concurrency/limiter"
 require_relative "shared_broker/middleware_pipeline"
@@ -20,27 +21,29 @@ require_relative "shared_broker/adapters/redis"
 
 module SharedBroker
   class << self
-    attr_accessor :encryption_key
+    attr_accessor :encryption_key, :key_provider
   end
 
   # Default key for development/test if not set
   @encryption_key = ENV.fetch("SHARED_BROKER_ENCRYPTION_KEY") { "a" * 32 }
+  @key_provider = nil
 
   class Client
     attr_reader :circuit_breaker, :middleware_pipeline, :adapters, :routing
 
-    def initialize(adapter: nil, adapters: nil, routing: nil, circuit_breaker: nil, middlewares: nil)
+    def initialize(adapter: nil, adapters: nil, routing: nil, circuit_breaker: nil, middlewares: nil, key_provider: nil)
       setup_adapters(adapter: adapter, adapters: adapters, routing: routing)
       @circuit_breaker = circuit_breaker || CircuitBreaker.new
       resolved_middlewares = middlewares || [SharedBroker::Middlewares::OpenTelemetryPropagation.new]
       @middleware_pipeline = MiddlewarePipeline.new(resolved_middlewares)
+      @key_provider = key_provider
     end
 
     def publish(topic, message, correlation_id: nil)
       metadata = { correlation_id: correlation_id, operation: :publish }
       @middleware_pipeline.execute(topic, message, metadata) do
         SharedBroker::Validation.validate!(topic, message)
-        encrypted_msg = SharedBroker::Cipher.encrypt(message, SharedBroker.encryption_key)
+        encrypted_msg = SharedBroker::Cipher.encrypt(message, active_key_provider, topic: topic)
 
         @circuit_breaker.run do
           resolve_adapter(topic).publish(topic, encrypted_msg, correlation_id: correlation_id)
@@ -57,7 +60,7 @@ module SharedBroker
 
       resolve_adapter(topic).subscribe(topic, queue_name, max_retries: max_retries, backoff_base: backoff_base) do |raw_message|
         limiter.run do
-          decrypted_msg = SharedBroker::Cipher.decrypt(raw_message, SharedBroker.encryption_key)
+          decrypted_msg = SharedBroker::Cipher.decrypt(raw_message, active_key_provider, topic: topic)
           SharedBroker::Validation.validate!(topic, decrypted_msg)
 
           metadata = { correlation_id: decrypted_msg[:_correlation_id], operation: :subscribe, queue_name: queue_name }
@@ -70,6 +73,10 @@ module SharedBroker
 
     private
 
+    def active_key_provider
+      @key_provider || SharedBroker.key_provider || SharedBroker::KeyProvider::Static.new(SharedBroker.encryption_key)
+    end
+
     def setup_adapters(adapter: nil, adapters: nil, routing: nil)
       if adapter || (adapters.nil? && routing.nil?)
         validate_single_adapter!(adapter)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shared_broker
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Wesley Lima
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -157,6 +157,7 @@ files:
 - lib/shared_broker/circuit_breaker.rb
 - lib/shared_broker/concurrency/limiter.rb
 - lib/shared_broker/concurrency/semaphore.rb
+- lib/shared_broker/key_provider.rb
 - lib/shared_broker/middleware_pipeline.rb
 - lib/shared_broker/middlewares/open_telemetry_propagation.rb
 - lib/shared_broker/schema_registry.rb