familia 2.0.0.pre14 → 2.0.0.pre16

data/lib/familia/distinguisher.rb

@@ -0,0 +1,85 @@
+# lib/familia/distinguisher.rb
+
+module Familia
+  module Distinguisher
+    # This method determines the appropriate transformation to apply based on
+    # the class of the input argument.
+    #
+    # @param [Object] value_to_distinguish The value to be processed. Keep in
+    #   mind that all data is stored as a string so whatever the type
+    #   of the value, it will be converted to a string.
+    # @param [Boolean] strict_values Whether to enforce strict value handling.
+    #   Defaults to true.
+    # @return [String, nil] The processed value as a string or nil for unsupported
+    #   classes.
+    #
+    # The method uses a case statement to handle different classes:
+    # - For `Symbol`, `String`, `Integer`, and `Float` classes, it traces the
+    #   operation and converts the value to a string.
+    # - For `Familia::Horreum` class, it traces the operation and returns the
+    #   identifier of the value.
+    # - For `TrueClass`, `FalseClass`, and `NilClass`, it traces the operation and
+    #   converts the value to a string ("true", "false", or "").
+    # - For any other class, it traces the operation and returns nil.
+    #
+    # Alternative names for `value_to_distinguish` could be `input_value`, `value`,
+    # or `object`.
+    #
+    def distinguisher(value_to_distinguish, strict_values: true)
+      case value_to_distinguish
+      when ::Symbol, ::String, ::Integer, ::Float
+        Familia.trace :TOREDIS_DISTINGUISHER, nil, 'string' if Familia.debug?
+
+        # Symbols and numerics are naturally serializable to strings
+        # so it's a relatively low risk operation.
+        value_to_distinguish.to_s
+
+      when ::TrueClass, ::FalseClass, ::NilClass
+        Familia.trace :TOREDIS_DISTINGUISHER, nil, 'true/false/nil' if Familia.debug?
+
+        # TrueClass, FalseClass, and NilClass are considered high risk because their
+        # original types cannot be reliably determined from their serialized string
+        # representations. This can lead to unexpected behavior during deserialization.
+        # For instance, a TrueClass value serialized as "true" might be deserialized as
+        # a String, causing application errors. Even more problematic, a NilClass value
+        # serialized as an empty string makes it impossible to distinguish between a
+        # nil value and an empty string upon deserialization. Such scenarios can result
+        # in subtle, hard-to-diagnose bugs. To mitigate these risks, we raise an
+        # exception when encountering these types unless the strict_values option is
+        # explicitly set to false.
+        #
+        raise Familia::NotDistinguishableError, value_to_distinguish if strict_values
+
+        value_to_distinguish.to_s #=> "true", "false", ""
+
+      when Familia::Base, Class
+        Familia.trace :TOREDIS_DISTINGUISHER, nil, 'base' if Familia.debug?
+
+        # When called with a class we simply transform it to its name. For
+        # instances of Familia class, we store the identifier.
+        if value_to_distinguish.is_a?(Class)
+          value_to_distinguish.name
+        else
+          value_to_distinguish.identifier
+        end
+
+      else
+        Familia.trace :TOREDIS_DISTINGUISHER, nil, "else1 #{strict_values}" if Familia.debug?
+
+        if value_to_distinguish.class.ancestors.member?(Familia::Base)
+          Familia.trace :TOREDIS_DISTINGUISHER, nil, 'isabase' if Familia.debug?
+
+          value_to_distinguish.identifier
+
+        else
+          Familia.trace :TOREDIS_DISTINGUISHER, nil, "else2 #{strict_values}" if Familia.debug?
+          raise Familia::NotDistinguishableError, value_to_distinguish if strict_values
+
+          nil
+        end
+      end
+    end
+  end
+
+  extend Distinguisher
+end

data/lib/familia/encryption/encrypted_data.rb

@@ -5,15 +5,15 @@ module Familia
     EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version) do
       # Class methods for parsing and validation
       def self.valid?(json_string)
-        return true if json_string.nil?  # Allow nil values
-        return false unless json_string.kind_of?(::String)
+        return true if json_string.nil? # Allow nil values
+        return false unless json_string.is_a?(::String)
 
         begin
           parsed = Familia::JsonSerializer.parse(json_string, symbolize_names: true)
           return false unless parsed.is_a?(Hash)
 
           # Check for required fields
-          required_fields = [:algorithm, :nonce, :ciphertext, :auth_tag, :key_version]
+          required_fields = %i[algorithm nonce ciphertext auth_tag key_version]
           result = required_fields.all? { |field| parsed.key?(field) }
           Familia.ld "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
           result
@@ -26,9 +26,7 @@ module Familia
       def self.validate!(json_string)
         return nil if json_string.nil?
 
-        unless json_string.kind_of?(::String)
-          raise EncryptionError, "Expected JSON string, got #{json_string.class}"
-        end
+        raise EncryptionError, "Expected JSON string, got #{json_string.class}" unless json_string.is_a?(::String)
 
         begin
           parsed = Familia::JsonSerializer.parse(json_string, symbolize_names: true)
@@ -36,16 +34,12 @@ module Familia
           raise EncryptionError, "Invalid JSON structure: #{e.message}"
         end
 
-        unless parsed.is_a?(Hash)
-          raise EncryptionError, "Expected JSON object, got #{parsed.class}"
-        end
+        raise EncryptionError, "Expected JSON object, got #{parsed.class}" unless parsed.is_a?(Hash)
 
-        required_fields = [:algorithm, :nonce, :ciphertext, :auth_tag, :key_version]
+        required_fields = %i[algorithm nonce ciphertext auth_tag key_version]
         missing_fields = required_fields.reject { |field| parsed.key?(field) }
 
-        unless missing_fields.empty?
-          raise EncryptionError, "Missing required fields: #{missing_fields.join(', ')}"
-        end
+        raise EncryptionError, "Missing required fields: #{missing_fields.join(', ')}" unless missing_fields.empty?
 
         new(**parsed)
       end
@@ -77,16 +71,12 @@ module Familia
       end
 
       def validate_decryptable!
-        unless algorithm
-          raise EncryptionError, "Missing algorithm field"
-        end
+        raise EncryptionError, 'Missing algorithm field' unless algorithm
 
         # Ensure Registry is set up before checking algorithms
         Registry.setup! if Registry.providers.empty?
 
-        unless Registry.providers.key?(algorithm)
-          raise EncryptionError, "Unsupported algorithm: #{algorithm}"
-        end
+        raise EncryptionError, "Unsupported algorithm: #{algorithm}" unless Registry.providers.key?(algorithm)
 
         unless nonce && ciphertext && auth_tag && key_version
           missing = []
@@ -107,22 +97,23 @@ module Familia
             raise EncryptionError, "Invalid nonce size: expected #{provider.nonce_size}, got #{decoded_nonce.bytesize}"
           end
         rescue ArgumentError
-          raise EncryptionError, "Invalid Base64 encoding in nonce field"
+          raise EncryptionError, 'Invalid Base64 encoding in nonce field'
         end
 
         begin
-          Base64.strict_decode64(ciphertext)  # ciphertext can be variable size
+          Base64.strict_decode64(ciphertext) # ciphertext can be variable size
         rescue ArgumentError
-          raise EncryptionError, "Invalid Base64 encoding in ciphertext field"
+          raise EncryptionError, 'Invalid Base64 encoding in ciphertext field'
         end
 
         begin
           decoded_auth_tag = Base64.strict_decode64(auth_tag)
           if decoded_auth_tag.bytesize != provider.auth_tag_size
-            raise EncryptionError, "Invalid auth_tag size: expected #{provider.auth_tag_size}, got #{decoded_auth_tag.bytesize}"
+            raise EncryptionError,
+                  "Invalid auth_tag size: expected #{provider.auth_tag_size}, got #{decoded_auth_tag.bytesize}"
           end
         rescue ArgumentError
-          raise EncryptionError, "Invalid Base64 encoding in auth_tag field"
+          raise EncryptionError, 'Invalid Base64 encoding in auth_tag field'
         end
 
         # Validate that the key version exists

data/lib/familia/encryption/manager.rb

@@ -39,7 +39,8 @@ module Familia
         Familia::Encryption.derivation_count.increment
 
         begin
-          data = Familia::Encryption::EncryptedData.new(**Familia::JsonSerializer.parse(encrypted_json, symbolize_names: true))
+          data = Familia::Encryption::EncryptedData.new(**Familia::JsonSerializer.parse(encrypted_json,
+                                                                                        symbolize_names: true))
 
           # Validate algorithm support
           provider = Registry.get(data.algorithm)
@@ -67,15 +68,16 @@ module Familia
       def decode_and_validate(encoded, expected_size, component)
         decoded = Base64.strict_decode64(encoded)
         raise EncryptionError, 'Invalid encrypted data' unless decoded.bytesize == expected_size
+
         decoded
-      rescue ArgumentError => e
+      rescue ArgumentError
         raise EncryptionError, "Invalid Base64 encoding in #{component} field"
       end
 
       def decode_and_validate_ciphertext(encoded)
         Base64.strict_decode64(encoded)
-      rescue ArgumentError => e
-        raise EncryptionError, "Invalid Base64 encoding in ciphertext field"
+      rescue ArgumentError
+        raise EncryptionError, 'Invalid Base64 encoding in ciphertext field'
       end
 
       def derive_key(context, version: nil, provider: nil)

data/lib/familia/encryption/providers/aes_gcm_provider.rb

@@ -49,7 +49,7 @@ module Familia
           {
             ciphertext: ciphertext,
             auth_tag: cipher.auth_tag,
-            nonce: nonce
+            nonce: nonce,
           }
         end
 

data/lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb

@@ -95,9 +95,7 @@ module Familia
           validate_key_length!(master_key)
 
           raw_personal = personal || Familia.config.encryption_personalization
-          if raw_personal.include?("\0")
-            raise EncryptionError, 'Personalization string must not contain null bytes'
-          end
+          raise EncryptionError, 'Personalization string must not contain null bytes' if raw_personal.include?("\0")
 
           personal_string = raw_personal.ljust(16, "\0")
 
@@ -132,8 +130,8 @@ module Familia
 
           result = {
             ciphertext: ciphertext_with_tag[0...-16],
-            auth_tag: ciphertext_with_tag[-16..-1],
-            nonce: nonce
+            auth_tag: ciphertext_with_tag[-16..],
+            nonce: nonce,
           }
 
           # Clear intermediate values
@@ -168,10 +166,10 @@ module Familia
         def clear_aead_instance(aead_instance)
           # Attempt to clear RbNaCl's internal key storage
           # This is a best-effort cleanup since RbNaCl stores keys as strings internally
-          if aead_instance.instance_variable_defined?(:@key)
-            internal_key = aead_instance.instance_variable_get(:@key)
-            secure_wipe(internal_key) if internal_key
-          end
+          return unless aead_instance.instance_variable_defined?(:@key)
+
+          internal_key = aead_instance.instance_variable_get(:@key)
+          secure_wipe(internal_key) if internal_key
         end
 
         def validate_key_length!(key)

data/lib/familia/encryption/providers/xchacha20_poly1305_provider.rb

@@ -53,8 +53,8 @@ module Familia
 
           {
             ciphertext: ciphertext_with_tag[0...-16],
-            auth_tag: ciphertext_with_tag[-16..-1],
-            nonce: nonce
+            auth_tag: ciphertext_with_tag[-16..],
+            nonce: nonce,
           }
         end
 
@@ -88,9 +88,8 @@ module Familia
         def derive_key(master_key, context, personal: nil)
           validate_key_length!(master_key)
           raw_personal = personal || Familia.config.encryption_personalization
-          if raw_personal.include?("\0")
-            raise EncryptionError, 'Personalization string must not contain null bytes'
-          end
+          raise EncryptionError, 'Personalization string must not contain null bytes' if raw_personal.include?("\0")
+
           personal_string = raw_personal.ljust(16, "\0")
 
           RbNaCl::Hash.blake2b(

data/lib/familia/encryption/request_cache.rb

@@ -18,8 +18,8 @@ module Familia
     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] = {}
+        Fiber[:familia_request_cache_enabled] = true
+        Fiber[:familia_request_cache] = {}
         yield
       ensure
         clear_request_cache!
@@ -27,12 +27,12 @@ module Familia
 
       # Clear all cached keys and disable caching
       def clear_request_cache!
-        if (cache = Thread.current[:familia_request_cache])
+        if (cache = Fiber[: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
+        Fiber[:familia_request_cache_enabled] = false
+        Fiber[:familia_request_cache] = nil
       end
 
       private
@@ -43,8 +43,8 @@ module Familia
         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] ||= {}
+        if Fiber[:familia_request_cache_enabled]
+          cache = Fiber[:familia_request_cache] ||= {}
           cache_key = "#{version}:#{context}"
 
           # Return cached key if available (within same request only)

data/lib/familia/encryption.rb

@@ -16,7 +16,6 @@ module Familia
   class EncryptionError < StandardError; end
 
   module Encryption
-
     # Smart facade with provider selection and field-specific encryption
     #
     # Usage in EncryptedFieldType can now be more flexible:
@@ -109,7 +108,7 @@ module Familia
           preferred_available: Registry.default_provider&.class&.name,
           using_hardware: hardware_acceleration?,
           key_versions: encryption_keys.keys,
-          current_version: current_key_version
+          current_version: current_key_version,
         }
       end
 
@@ -140,7 +139,7 @@ module Familia
           results[algo] = {
             time: time,
             ops_per_sec: (iterations * 2 / time).round,
-            priority: provider_class.priority
+            priority: provider_class.priority,
           }
         end
 

data/lib/familia/errors.rb

@@ -10,7 +10,10 @@ module Familia
 
   class SerializerError < Problem; end
 
-  class HighRiskFactor < Problem
+  # Raised when attempting to start transactions or pipelines on connection types that don't support them
+  class OperationModeError < Problem; end
+
+  class NotDistinguishableError < Problem
     attr_reader :value
 
     def initialize(value)
@@ -19,7 +22,7 @@ module Familia
     end
 
     def message
-      "High risk factor for serialization bugs: #{value}<#{value.class}>"
+      "Cannot represent #{value}<#{value.class}> as a string"
     end
   end
 
@@ -36,9 +39,12 @@ module Familia
     end
   end
 
-  # Set Familia.connection_provider or use middleware to provide connections.
+  # UnsortedSet Familia.connection_provider or use middleware to provide connections.
   class NoConnectionAvailable < Problem; end
 
+  # Raised when a load method fails to find the requested object
+  class NotFound < Problem; end
+
   # Raised when attempting to refresh an object whose key doesn't exist in the database
   class KeyNotFoundError < NonUniqueKey
     attr_reader :key

data/lib/familia/{autoloader.rb → features/autoloader.rb}

@@ -1,11 +1,39 @@
-# frozen_string_literal: true
+# lib/familia/features/autoloader.rb
 
-module Familia
+# rubocop:disable Style/ClassAndModuleChildren
+module Familia::Features
   # Provides autoloading functionality for Ruby files based on patterns and conventions.
   #
   # Used by the Features module at library startup to load feature files, and available
   # as a utility for other modules requiring file autoloading capabilities.
   module Autoloader
+    using Familia::Refinements::StylizeWords
+
+    # Autoloads feature files when this module is included.
+    #
+    # Discovers and loads all Ruby files in the features/ directory relative to the
+    # including module's location. Typically used by Familia::Features.
+    #
+    # @param base [Module] the module including this autoloader
+    def self.included(base)
+      # Get the directory where the including module is defined
+      # This should be lib/familia for the Features module
+      base_path = File.dirname(caller_locations(1, 1).first.path)
+      config_name = normalize_to_config_name(base.name)
+
+      dir_patterns = [
+        File.join(base_path, 'features', '*.rb'),
+        File.join(base_path, config_name, 'features', '*.rb'),
+        File.join(base_path, config_name, 'features.rb'),
+      ]
+
+      # Ensure the Features module exists within the base module
+      base.const_set(:Features, Module.new) unless base.const_defined?(:Features) || config_name.eql?('features')
+
+      # Use the shared autoload_files method
+      autoload_files(dir_patterns, log_prefix: "Autoloader[#{config_name}]")
+    end
+
     # Autoloads Ruby files matching the given patterns.
     #
     # @param patterns [String, Array<String>] file patterns to match (supports Dir.glob patterns)
@@ -15,39 +43,37 @@ module Familia
       patterns = Array(patterns)
 
       patterns.each do |pattern|
+        Familia.trace :AUTOLOAD, nil, "[#{log_prefix}] Autoloader loading features from #{pattern}"
         Dir.glob(pattern).each do |file_path|
           basename = File.basename(file_path)
 
           # Skip excluded files
           next if exclude.include?(basename)
 
-          Familia.trace :FEATURE, nil, "[#{log_prefix}] Loading #{file_path}", caller(1..1) if Familia.debug?
+          Familia.trace :FEATURE, nil, "[#{log_prefix}] Loading #{basename}" if Familia.debug?
           require File.expand_path(file_path)
         end
       end
     end
 
-    # Autoloads feature files when this module is included.
-    #
-    # Discovers and loads all Ruby files in the features/ directory relative to the
-    # including module's location. Typically used by Familia::Features.
-    #
-    # @param base [Module] the module including this autoloader
-    def self.included(base)
-      # Get the directory where the including module is defined
-      # This should be lib/familia for the Features module
-      base_path = File.dirname(caller_locations(1, 1).first.path)
-      features_dir = File.join(base_path, 'features')
-
-      Familia.ld "[DEBUG] Autoloader loading features from #{features_dir}"
+    class << self
+      # Converts the value into a string that can be used to look up configuration
+      # values or system paths. This replicates the normalization done by the
+      # Familia::Horreum model class config_name method.
+      #
+      # @see Familia::Horreum::DefinitionMethods#config_name
+      #
+      # NOTE: We don't call that existing method directly b/c Autoloader is meant
+      # to work for any class/module that matches `dir_patterns` (see `included`).
+      #
+      # @param value [String] the value to normalize (typically a class name)
+      # @return [String] the underscored value as a string
+      def normalize_to_config_name(value)
+        return nil if value.nil?
 
-      return unless Dir.exist?(features_dir)
-
-      # Use the shared autoload_files method
-      autoload_files(
-        File.join(features_dir, '*.rb'),
-        log_prefix: 'Autoloader'
-      )
+        value.demodularize.snake_case
+      end
     end
   end
 end
+# rubocop:enable Style/ClassAndModuleChildren

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

@@ -161,8 +161,8 @@ class ConcealedString
   # Prevent accidental exposure through string conversion and serialization
   #
   # Ruby has two string conversion methods with different purposes:
-  # - to_s: explicit conversion (obj.to_s, string interpolation "#{obj}")
-  # - to_str: implicit coercion (File.read(obj), "prefix" + obj)
+  # - to_s: explicit conversion (`obj.to_s`, string interpolation `"#{obj}"`)
+  # - to_str: implicit coercion (`File.read(obj)`, `"prefix" + obj`)
   #
   # We implement to_s for safe logging/debugging but deliberately omit to_str
   # to prevent encrypted data from being used where strings are expected.
@@ -268,7 +268,7 @@ class ConcealedString
 
   # Prevent exposure in JSON serialization - fail closed for security
   def to_json(*)
-    raise Familia::SerializerError, "ConcealedString cannot be serialized to JSON"
+    raise Familia::SerializerError, 'ConcealedString cannot be serialized to JSON'
   end
 
   # Prevent exposure in Rails serialization (as_json -> to_json)
@@ -291,5 +291,4 @@ class ConcealedString
   def encrypted_json?(data)
     Familia::Encryption::EncryptedData.valid?(data)
   end
-
 end

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

@@ -58,7 +58,7 @@ module Familia
 
           # If we have a raw string (from direct instance variable manipulation),
           # wrap it in ConcealedString which will trigger validation
-          if concealed.kind_of?(::String) && !concealed.is_a?(ConcealedString)
+          if concealed.is_a?(::String) && !concealed.is_a?(ConcealedString)
             # This happens when someone directly sets the instance variable
             # (e.g., during tampering tests). Wrapping in ConcealedString
             # will trigger validate_decryptable! and catch invalid algorithms
@@ -75,7 +75,8 @@ module Familia
           # Context validation: detect cross-context attacks
           # Only validate if we have a proper ConcealedString instance
           if concealed.is_a?(ConcealedString) && !concealed.belongs_to_context?(self, field_name)
-            raise Familia::EncryptionError, "Context isolation violation: encrypted field '#{field_name}' does not belong to #{self.class.name}:#{self.identifier}"
+            raise Familia::EncryptionError,
+                  "Context isolation violation: encrypted field '#{field_name}' does not belong to #{self.class.name}:#{identifier}"
           end
 
           concealed
@@ -90,13 +91,13 @@ module Familia
       field_name = @name
       method_name = @method_name
       fast_method_name = @fast_method_name
-      field_type = self
+      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?
 
-          # Set via the setter method to get proper ConcealedString wrapping
+          # UnsortedSet via the setter method to get proper ConcealedString wrapping
           send(:"#{method_name}=", val) if method_name
 
           # Get the ConcealedString and extract encrypted data for storage
@@ -203,18 +204,16 @@ module Familia
       if @aad_fields.empty?
         # When no AAD fields specified, use class:field:identifier
         base_components.join(':')
-      else
+      elsif record.exists?
         # For unsaved records, don't enforce AAD fields since they can change
         # For saved records, include field values for tamper protection
-        if record.exists?
-          # Include specified field values in AAD for persisted records
-          values = @aad_fields.map { |field| record.send(field) }
-          all_components = [*base_components, *values].compact
-          Digest::SHA256.hexdigest(all_components.join(':'))
-        else
-          # For unsaved records, only use class:field:identifier for context isolation
-          base_components.join(':')
-        end
+        values = @aad_fields.map { |field| record.send(field) }
+        all_components = [*base_components, *values].compact
+        Digest::SHA256.hexdigest(all_components.join(':'))
+      # Include specified field values in AAD for persisted records
+      else
+        # For unsaved records, only use class:field:identifier for context isolation
+        base_components.join(':')
       end
     end
   end