familia 2.0.0.pre3 → 2.0.0.pre5

data/lib/familia/encryption/registry.rb

@@ -0,0 +1,50 @@
+# lib/familia/encryption/registry.rb
+
+module Familia
+  module Encryption
+    # Registry pattern for managing encryption providers
+    class Registry
+      class << self
+        def providers
+          @providers ||= {}
+        end
+
+        def register(provider_class)
+          return unless provider_class.available?
+
+          providers[provider_class::ALGORITHM] = provider_class
+        end
+
+        def get(algorithm)
+          provider_class = providers[algorithm]
+          raise EncryptionError, "Unsupported algorithm: #{algorithm}" unless provider_class
+
+          provider_class.new
+        end
+
+        def default_provider
+          # Select provider with highest priority
+          @default_provider ||= begin
+            available = providers.values.select(&:available?)
+            available.max_by(&:priority)&.new
+          end
+        end
+
+        def reset_default_provider!
+          @default_provider = nil
+        end
+
+        def available_algorithms
+          providers.keys
+        end
+
+        # Auto-register known providers
+        def setup!
+          register(Providers::XChaCha20Poly1305Provider)
+          register(Providers::AESGCMProvider)
+          # Future: register(Providers::ChaCha20Poly1305Provider)
+        end
+      end
+    end
+  end
+end

data/lib/familia/encryption.rb

@@ -0,0 +1,178 @@
+# lib/familia/encryption.rb
+
+require 'base64'
+require 'json'
+require 'openssl'
+
+# Provider system components
+require_relative 'encryption/provider'
+require_relative 'encryption/providers/xchacha20_poly1305_provider'
+require_relative 'encryption/providers/aes_gcm_provider'
+require_relative 'encryption/registry'
+require_relative 'encryption/manager'
+
+module Familia
+  class EncryptionError < StandardError; end
+
+  module Encryption
+    EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version)
+
+    # Smart facade with provider selection and field-specific encryption
+    #
+    # Usage in EncryptedFieldType can now be more flexible:
+    #
+    #   module Familia
+    #     class EncryptedFieldType < FieldType
+    #       attr_reader :algorithm  # Optional algorithm override
+    #
+    #       def initialize(name, aad_fields: [], algorithm: nil, **options)
+    #         super(name, **options.merge(on_conflict: :raise))
+    #         @aad_fields = Array(aad_fields).freeze
+    #         @algorithm = algorithm  # Use specific algorithm for this field
+    #       end
+    #
+    #       def encrypt_value(record, value)
+    #         context = build_context(record)
+    #         additional_data = build_aad(record)
+    #
+    #         if @algorithm
+    #           # Use specific algorithm for this field
+    #           Familia::Encryption.encrypt_with(@algorithm, value,
+    #             context: context,
+    #             additional_data: additional_data)
+    #         else
+    #           # Use default best algorithm
+    #           Familia::Encryption.encrypt(value,
+    #             context: context,
+    #             additional_data: additional_data)
+    #         end
+    #       end
+    #
+    #       # Decrypt auto-detects algorithm from data, so no change needed
+    #       def decrypt_value(record, encrypted)
+    #         context = build_context(record)
+    #         additional_data = build_aad(record)
+    #
+    #         Familia::Encryption.decrypt(encrypted,
+    #           context: context,
+    #           additional_data: additional_data)
+    #       end
+    #     end
+    #   end
+    class << self
+      # Get or create a manager with specific algorithm
+      def manager(algorithm: nil)
+        @managers ||= {}
+        @managers[algorithm] ||= Manager.new(algorithm: algorithm)
+      end
+
+      # Quick encryption with auto-selected best provider
+      def encrypt(plaintext, context:, additional_data: nil)
+        manager.encrypt(plaintext, context: context, additional_data: additional_data)
+      end
+
+      # Quick decryption (auto-detects algorithm from data)
+      def decrypt(encrypted_json, context:, additional_data: nil)
+        manager.decrypt(encrypted_json, context: context, additional_data: additional_data)
+      end
+
+      # Encrypt with specific algorithm
+      def encrypt_with(algorithm, plaintext, context:, additional_data: nil)
+        manager(algorithm: algorithm).encrypt(
+          plaintext,
+          context: context,
+          additional_data: additional_data
+        )
+      end
+
+      # Derivation counter for monitoring no-caching behavior
+      def derivation_count
+        @derivation_count ||= Concurrent::AtomicFixnum.new(0)
+      end
+
+      def reset_derivation_count!
+        derivation_count.value = 0
+      end
+
+      # Clear key from memory (no security guarantees in Ruby)
+      def secure_wipe(key)
+        key&.clear
+      end
+
+      # Get info about current encryption setup
+      def status
+        Registry.setup! if Registry.providers.empty?
+
+        {
+          default_algorithm: Registry.default_provider&.algorithm,
+          available_algorithms: Registry.available_algorithms,
+          preferred_available: Registry.default_provider&.class&.name,
+          using_hardware: hardware_acceleration?,
+          key_versions: encryption_keys.keys,
+          current_version: current_key_version
+        }
+      end
+
+      # Check if we're using hardware acceleration
+      def hardware_acceleration?
+        provider = Registry.default_provider
+        provider && provider.class.name.include?('Hardware')
+      end
+
+      # Benchmark available providers
+      def benchmark(iterations: 1000)
+        require 'benchmark'
+        test_data = 'x' * 1024 # 1KB test
+        context = 'benchmark:test'
+
+        results = {}
+        Registry.providers.each do |algo, provider_class|
+          next unless provider_class.available?
+
+          mgr = Manager.new(algorithm: algo)
+          time = Benchmark.realtime do
+            iterations.times do
+              encrypted = mgr.encrypt(test_data, context: context)
+              mgr.decrypt(encrypted, context: context)
+            end
+          end
+
+          results[algo] = {
+            time: time,
+            ops_per_sec: (iterations * 2 / time).round,
+            priority: provider_class.priority
+          }
+        end
+
+        results
+      end
+
+      def validate_configuration!
+        raise EncryptionError, 'No encryption keys configured' if encryption_keys.empty?
+        raise EncryptionError, 'No current key version set' unless current_key_version
+
+        current_key = encryption_keys[current_key_version]
+        raise EncryptionError, "Current key version not found: #{current_key_version}" unless current_key
+
+        begin
+          Base64.strict_decode64(current_key)
+        rescue ArgumentError
+          raise EncryptionError, 'Current encryption key is not valid Base64'
+        end
+
+        Registry.setup!
+        raise EncryptionError, 'No encryption providers available' unless Registry.default_provider
+      end
+
+      private
+
+      def encryption_keys
+        Familia.config.encryption_keys || {}
+      end
+
+      def current_key_version
+        Familia.config.current_key_version
+      end
+    end
+  end
+end

data/lib/familia/encryption_request_cache.rb

@@ -0,0 +1,68 @@
+# lib/familia/encryption_request_cache.rb
+#
+# Request-scoped caching for encryption keys (if needed for performance)
+# This should ONLY be enabled if performance testing shows it's necessary
+#
+# Usage in Rack middleware:
+#   class ClearEncryptionCacheMiddleware
+#     def call(env)
+#       Familia::Encryption.clear_request_cache!
+#       @app.call(env)
+#     ensure
+#       Familia::Encryption.clear_request_cache!
+#     end
+#   end
+
+module Familia
+  module Encryption
+    class << self
+      # Enable request-scoped caching (opt-in for performance)
+      def with_request_cache
+        Thread.current[:familia_request_cache_enabled] = true
+        Thread.current[:familia_request_cache] = {}
+        yield
+      ensure
+        clear_request_cache!
+      end
+
+      # Clear all cached keys and disable caching
+      def clear_request_cache!
+        if (cache = Thread.current[:familia_request_cache])
+          cache.each_value { |key| secure_wipe(key) }
+          cache.clear
+        end
+        Thread.current[:familia_request_cache_enabled] = false
+        Thread.current[:familia_request_cache] = nil
+      end
+
+      private
+
+      # Modified derive_key that uses request cache when enabled
+      def derive_key_with_optional_cache(context, version: nil)
+        version ||= current_key_version
+        master_key = get_master_key(version)
+
+        # Only use cache if explicitly enabled for this request
+        if Thread.current[:familia_request_cache_enabled]
+          cache = Thread.current[:familia_request_cache] ||= {}
+          cache_key = "#{version}:#{context}"
+
+          # Return cached key if available (within same request only)
+          if (cached = cache[cache_key])
+            return cached.dup
+          end
+
+          # Derive and cache for this request only
+          derived = perform_key_derivation(master_key, context)
+          cache[cache_key] = derived.dup
+          derived
+        else
+          # Default: no caching for maximum security
+          perform_key_derivation(master_key, context)
+        end
+      ensure
+        secure_wipe(master_key) if master_key
+      end
+    end
+  end
+end

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -0,0 +1,153 @@
+# lib/familia/field_types/encrypted_field_type.rb
+
+require_relative '../../field_type'
+
+module Familia
+  class EncryptedFieldType < FieldType
+    attr_reader :aad_fields
+
+    def initialize(name, aad_fields: [], **options)
+      super(name, **options.merge(on_conflict: :raise))
+      @aad_fields = Array(aad_fields).freeze
+    end
+
+    def define_setter(klass)
+      field_name = @name
+      method_name = @method_name
+      field_type = self
+
+      handle_method_conflict(klass, :"#{method_name}=") do
+        klass.define_method :"#{method_name}=" do |value|
+          encrypted = value.nil? ? nil : field_type.encrypt_value(self, value)
+          instance_variable_set(:"@#{field_name}", encrypted)
+        end
+      end
+    end
+
+    def define_getter(klass)
+      field_name = @name
+      method_name = @method_name
+      field_type = self
+
+      handle_method_conflict(klass, method_name) do
+        klass.define_method method_name do
+          encrypted = instance_variable_get(:"@#{field_name}")
+          encrypted.nil? ? nil : field_type.decrypt_value(self, encrypted)
+        end
+      end
+    end
+
+    def define_fast_writer(klass)
+      # Encrypted fields override base fast writer for security
+      return unless @fast_method_name&.to_s&.end_with?('!')
+
+      field_name = @name
+      method_name = @method_name
+      fast_method_name = @fast_method_name
+      field_type = self
+
+      handle_method_conflict(klass, fast_method_name) do
+        klass.define_method fast_method_name do |val|
+          raise ArgumentError, "#{fast_method_name} requires a value" if val.nil?
+
+          encrypted = field_type.encrypt_value(self, val)
+          send(:"#{method_name}=", val) if method_name
+
+          ret = hset(field_name, encrypted)
+          ret.zero? || ret.positive?
+        end
+      end
+    end
+
+    # Encrypt a value for the given record
+    def encrypt_value(record, value)
+      context = build_context(record)
+      additional_data = build_aad(record)
+
+      Familia::Encryption.encrypt(value, context: context, additional_data: additional_data)
+    end
+
+    # Decrypt a value for the given record
+    def decrypt_value(record, encrypted)
+      context = build_context(record)
+      additional_data = build_aad(record)
+
+      Familia::Encryption.decrypt(encrypted, context: context, additional_data: additional_data)
+    end
+
+    def persistent?
+      true
+    end
+
+    def category
+      :encrypted
+    end
+
+    private
+
+    # Build encryption context string
+    def build_context(record)
+      "#{record.class.name}:#{@name}:#{record.identifier}"
+    end
+
+    # Build Additional Authenticated Data (AAD) for authenticated encryption
+    #
+    # AAD provides cryptographic binding between encrypted field values and their
+    # containing record context. This prevents attackers from moving encrypted
+    # values between different records or field contexts, even with database access.
+    #
+    # ## Persistence-Dependent Behavior
+    #
+    # AAD is only generated for records that exist in the database (`record.exists?`).
+    # This creates an important behavioral distinction:
+    #
+    # **Before Save (record.exists? == false):**
+    # - AAD = nil
+    # - Encryption context = "ClassName:fieldname:identifier" only
+    # - Values can be encrypted/decrypted freely in memory
+    #
+    # **After Save (record.exists? == true):**
+    # - AAD = record.identifier (no aad_fields) or SHA256(identifier:field1:field2:...)
+    # - Full cryptographic binding to database state
+    # - Moving encrypted values between records/contexts will fail decryption
+    #
+    # ## Security Implications
+    #
+    # This design prevents several attack vectors:
+    #
+    # 1. **Field Value Swapping**: With aad_fields specified, encrypted values
+    #    become bound to other field values. Changing owner_id breaks decryption.
+    #
+    # 2. **Cross-Record Migration**: Even without aad_fields, encrypted values
+    #    are bound to their specific record identifier after persistence.
+    #
+    # 3. **Temporal Consistency**: Re-encrypting the same plaintext after
+    #    field changes produces different ciphertext due to AAD changes.
+    #
+    # ## Usage Patterns
+    #
+    # ```ruby
+    # # No AAD fields - basic record binding
+    # encrypted_field :secret_value
+    #
+    # # With AAD fields - multi-field binding
+    # encrypted_field :content, aad_fields: [:owner_id, :doc_type]
+    # ```
+    #
+    # @param record [Familia::Horreum] The record instance containing this field
+    # @return [String, nil] AAD string for encryption, or nil for unsaved records
+    #
+    def build_aad(record)
+      return nil unless record.exists?
+
+      if @aad_fields.empty?
+        # When no AAD fields specified, just use identifier
+        record.identifier
+      else
+        # Include specified field values in AAD
+        values = @aad_fields.map { |field| record.send(field) }
+        Digest::SHA256.hexdigest([record.identifier, *values].compact.join(':'))
+      end
+    end
+  end
+end

data/lib/familia/features/encrypted_fields.rb

@@ -0,0 +1,28 @@
+# lib/familia/features/encrypted_fields.rb
+
+require_relative 'encrypted_fields/encrypted_field_type'
+
+module Familia
+  module Features
+    module EncryptedFields
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Define an encrypted field
+        # @param name [Symbol] Field name
+        # @param aad_fields [Array<Symbol>] Optional fields to include in AAD
+        # @param kwargs [Hash] Additional field options
+        def encrypted_field(name, aad_fields: [], **)
+          require_relative 'encrypted_fields/encrypted_field_type'
+
+          field_type = EncryptedFieldType.new(name, aad_fields: aad_fields, **)
+          register_field_type(field_type)
+        end
+      end
+
+      Familia::Base.add_feature self, :encrypted_fields
+    end
+  end
+end

data/lib/familia/features/expiration.rb

@@ -1,100 +1,130 @@
 # lib/familia/features/expiration.rb
 
+module Familia
+  module Features
+    # Famnilia::Features::Expiration
+    #
+    module Expiration
+      @default_expiration = nil
 
-module Familia::Features
+      def self.included(base)
+        Familia.ld "[#{base}] Loaded #{self}"
+        base.extend ClassMethods
 
-  module Expiration
-    @default_expiration = nil
+        # Optionally define default_expiration in the class to make
+        # sure we always have an array to work with.
+        return if base.instance_variable_defined?(:@default_expiration)
 
-    module ClassMethods
+        base.instance_variable_set(:@default_expiration, @default_expiration) # set above
+      end
 
-      attr_writer :default_expiration
+      # ClassMethods
+      #
+      module ClassMethods
+        attr_writer :default_expiration
 
-      def default_expiration(v = nil)
-        @default_expiration = v.to_f unless v.nil?
-        @default_expiration || parent&.default_expiration || Familia.default_expiration
+        def default_expiration(num = nil)
+          @default_expiration = num.to_f unless num.nil?
+          @default_expiration || parent&.default_expiration || Familia.default_expiration
+        end
       end
 
-    end
-
-    def self.included base
-      Familia.ld "[#{base}] Loaded #{self}"
-      base.extend ClassMethods
+      def default_expiration=(num)
+        @default_expiration = num.to_f
+      end
 
-      # Optionally define default_expiration in the class to make
-      # sure we always have an array to work with.
-      unless base.instance_variable_defined?(:@default_expiration)
-        base.instance_variable_set(:@default_expiration, @default_expiration) # set above
+      def default_expiration
+        @default_expiration || self.class.default_expiration
       end
-    end
 
-    def default_expiration=(v)
-      @default_expiration = v.to_f
-    end
+      # Sets an expiration time for the Database data associated with this object.
+      #
+      # This method allows setting a Time To Live (TTL) for the data in Redis,
+      # after which it will be automatically removed.
+      #
+      # @param default_expiration [Integer, nil] The Time To Live in seconds. If nil, the default
+      #   TTL will be used.
+      #
+      # @return [Boolean] Returns true if the expiration was set successfully,
+      #   false otherwise.
+      #
+      # @example Setting an expiration of one day
+      #   object.update_expiration(default_expiration: 86400)
+      #
+      # @note If Default expiration is set to zero, the expiration will be removed, making the
+      #   data persist indefinitely.
+      #
+      # @raise [Familia::Problem] Raises an error if the default expiration is not a non-negative
+      #   integer.
+      #
+      def update_expiration(default_expiration: nil)
+        default_expiration ||= self.default_expiration
+
+        if self.class.has_relations?
+          Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
+          self.class.related_fields.each do |name, definition|
+            next if definition.opts[:default_expiration].nil?
+
+            obj = send(name)
+            Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
+            obj.update_expiration(default_expiration: default_expiration)
+          end
+        end
+
+        # It's important to raise exceptions here and not just log warnings. We
+        # don't want to silently fail at setting expirations and cause data
+        # retention issues (e.g. not removed in a timely fashion).
+        #
+        # For the same reason, we don't want to default to 0 bc there's not a
+        # good reason for the default_expiration to not be set in the first place. If the
+        # class doesn't have a default_expiration, the default comes from
+        # Familia.default_expiration (which is 0, aka no-op/skip/do nothing).
+        unless default_expiration.is_a?(Numeric)
+          raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} in #{self.class})"
+        end
 
-    def default_expiration
-      @default_expiration || self.class.default_expiration
+        # If zero, simply skips setting an expiry for this key. If we were to set
+        # 0 the database would drop the key immediately.
+        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})" if default_expiration.zero?
+
+        Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
+
+        # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
+        # not exist or the timeout could not be set. Via redis-rb here, it's
+        # a bool.
+        expire(default_expiration)
+      end
+
+      Familia::Base.add_feature self, :expiration
     end
+  end
+end
 
-    # Sets an expiration time for the Database data associated with this object.
-    #
-    # This method allows setting a Time To Live (TTL) for the data in Redis,
-    # after which it will be automatically removed.
-    #
-    # @param default_expiration [Integer, nil] The Time To Live in seconds. If nil, the default
-    #   TTL will be used.
+module Familia
+  # Add a default update_expiration method for all classes that include
+  # Familia::Base. Since expiration is a core feature, we can confidently
+  # call `horreum_instance.update_expiration` without defensive programming
+  # even when expiration is not enabled for the horreum_instance class.
+  module Base
+    # Base implementation of update_expiration that maintains API compatibility
+    # with the :expiration feature's implementation.
     #
-    # @return [Boolean] Returns true if the expiration was set successfully,
-    #   false otherwise.
+    # This is a no-op implementation that gets overridden by features like
+    # :expiration. It accepts an optional default_expiration parameter to maintain interface
+    # compatibility with the overriding implementations.
     #
-    # @example Setting an expiration of one day
-    #   object.update_expiration(default_expiration: 86400)
+    # @param default_expiration [Integer, nil] Time To Live in seconds
+    # @return [nil] Always returns nil
     #
-    # @note If Default expiration is set to zero, the expiration will be removed, making the
-    #   data persist indefinitely.
-    #
-    # @raise [Familia::Problem] Raises an error if the default expiration is not a non-negative
-    #   integer.
+    # @note This is a no-op implementation. Classes that need expiration
+    #       functionality should include the :expiration feature.
     #
     def update_expiration(default_expiration: nil)
-      default_expiration ||= self.default_expiration
-
-      if self.class.has_relations?
-        Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
-        self.class.related_fields.each do |name, definition|
-          next if definition.opts[:default_expiration].nil?
-          obj = send(name)
-          Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
-          obj.update_expiration(default_expiration: default_expiration)
-        end
-      end
-
-      # It's important to raise exceptions here and not just log warnings. We
-      # don't want to silently fail at setting expirations and cause data
-      # retention issues (e.g. not removed in a timely fashion).
-      #
-      # For the same reason, we don't want to default to 0 bc there's not a
-      # good reason for the default_expiration to not be set in the first place. If the
-      # class doesn't have a default_expiration, the default comes from Familia.default_expiration (which
-      # is 0).
-      unless default_expiration.is_a?(Numeric)
-        raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} in #{self.class})"
-      end
-
-      if default_expiration.zero?
-        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
-      end
-
-      Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
-
-      # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
-      # not exist or the timeout could not be set. Via redis-rb here, it's
-      # a bool.
-      expire(default_expiration)
+      Familia.ld <<~LOG
+        [update_expiration] Feature not enabled for #{self.class}.
+        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
+      LOG
+      nil
     end
-    extend ClassMethods
-
-    Familia::Base.add_feature self, :expiration
   end
-
 end