familia 2.0.0.pre3 → 2.0.0.pre5

data/lib/familia/settings.rb

@@ -1,16 +1,18 @@
 # lib/familia/settings.rb
 
 module Familia
-
   @delim = ':'
   @prefix = nil
   @suffix = :object
   @default_expiration = 0 # see update_expiration. Zero is skip. nil is an exception.
   @logical_database = nil
+  @encryption_keys = nil
+  @current_key_version = nil
+  @encryption_personalization = 'FamilialMatters'
 
   module Settings
-
-    attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix
+    attr_writer :delim, :suffix, :default_expiration, :logical_database, :prefix, :encryption_keys,
+                :current_key_version, :encryption_personalization
 
     def delim(val = nil)
       @delim = val if val
@@ -44,5 +46,39 @@ module Familia
       suffix
     end
 
+    def encryption_keys(val = nil)
+      @encryption_keys = val if val
+      @encryption_keys
+    end
+
+    def current_key_version(val = nil)
+      @current_key_version = val if val
+      @current_key_version
+    end
+
+    # Personalization string for BLAKE2b key derivation in XChaCha20Poly1305.
+    # This provides cryptographic domain separation, ensuring derived keys are
+    # unique per application even with identical master keys and contexts.
+    # Must be 16 bytes or less (automatically padded with null bytes).
+    #
+    # @example
+    #   Familia.configure do |config|
+    #     config.encryption_personalization = 'MyApp1.0'
+    #   end
+    #
+    # @param val [String, nil] The personalization string, or nil to get current value
+    # @return [String] Current personalization string
+    def encryption_personalization(val = nil)
+      if val
+        raise ArgumentError, 'Personalization string cannot exceed 16 bytes' if val.bytesize > 16
+
+        @encryption_personalization = val
+      end
+      @encryption_personalization
+    end
+
+    def config
+      self
+    end
   end
 end

data/lib/familia/utils.rb

@@ -1,6 +1,9 @@
 # lib/familia/utils.rb
 
 module Familia
+
+  # Family-related utility methods
+  #
   module Utils
 
     # Joins array elements with Familia delimiter
@@ -145,5 +148,47 @@ module Familia
       end
     end
 
+    # Converts an absolute file path to a path relative to the current working
+    # directory. This simplifies logging and error reporting by showing
+    # only the relevant parts of file paths instead of lengthy absolute paths.
+    #
+    # @param filepath [String, Pathname] The file path to convert
+    # @return [Pathname, String, nil] A relative path from current directory,
+    #   basename if path goes outside current directory, or nil if filepath is nil
+    #
+    # @example Using current directory as base
+    #   Utils.pretty_path("/home/dev/project/lib/config.rb") # => "lib/config.rb"
+    #
+    # @example Path outside current directory
+    #   Utils.pretty_path("/etc/hosts") # => "hosts"
+    #
+    # @example Nil input
+    #   Utils.pretty_path(nil) # => nil
+    #
+    # @see Pathname#relative_path_from Ruby standard library documentation
+    def pretty_path(filepath)
+      return nil if filepath.nil?
+
+      basepath = Dir.pwd
+      relative_path = Pathname.new(filepath).relative_path_from(basepath)
+      if relative_path.to_s.start_with?('..')
+        File.basename(filepath)
+      else
+        relative_path
+      end
+    end
+
+    # Formats a stack trace with pretty file paths for improved readability
+    #
+    # @param limit [Integer] Maximum number of stack frames to include (default: 3)
+    # @return [String] Formatted stack trace with relative paths joined by newlines
+    #
+    # @example
+    #   Utils.pretty_stack(limit: 10)
+    #   # => "lib/models/user.rb:25:in `save'\n lib/controllers/app.rb:45:in `create'"
+    def pretty_stack(skip: 1, limit: 5)
+      caller(skip..(skip + limit + 1)).first(limit).map { |frame| pretty_path(frame) }.join("\n")
+    end
+
   end
 end

data/lib/familia/version.rb

@@ -3,6 +3,6 @@
 module Familia
   # Version information for the Familia
   unless defined?(Familia::VERSION)
-    VERSION = '2.0.0.pre3'
+    VERSION = '2.0.0.pre5'
   end
 end

data/lib/familia.rb

@@ -81,5 +81,6 @@ end
 
 require_relative 'familia/base'
 require_relative 'familia/features'
-require_relative 'familia/datatype'
+require_relative 'familia/data_type'
 require_relative 'familia/horreum'
+require_relative 'familia/encryption'

data/try/core/base_enhancements_try.rb

@@ -0,0 +1,115 @@
+# try/core/base_enhancements_try.rb
+
+require_relative '../helpers/test_helpers'
+
+Familia.debug = false
+
+# Base class provides default UUID generation
+class BaseUuidTest < Familia::Horreum
+  identifier_field :id
+  field :id
+end
+
+# Empty class still has base functionality
+class EmptyBaseTest < Familia::Horreum
+end
+
+@base_uuid = BaseUuidTest.new(id: 'uuid_test_1')
+
+## UUID generation creates unique identifiers
+@uuid1 = @base_uuid.uuid
+@uuid1
+#=:> String
+
+## UUID is properly formatted
+@uuid1
+#=~>/\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+
+## UUID is memoized (same value on repeated calls)
+@uuid2 = @base_uuid.uuid
+@uuid1 == @uuid2
+#=> true
+
+## Different instances get different UUIDs
+@base_uuid2 = BaseUuidTest.new(id: 'uuid_test_2')
+@base_uuid.uuid != @base_uuid2.uuid
+#=> true
+
+## Base class provides ID generation
+@generated_id1 = @base_uuid.generate_id
+@generated_id1
+#=:> String
+
+## Generated ID is memoized
+@generated_id2 = @base_uuid.generate_id
+@generated_id1 == @generated_id2
+#=> true
+
+## Base class to_s method returns identifier
+@base_uuid.to_s
+#=> "uuid_test_1"
+
+## Feature registry is accessible
+Familia::Base.features_available
+#=:> Hash
+
+## Feature definitions registry is accessible
+Familia::Base.feature_definitions
+#=:> Hash
+
+## Base class includes proper modules
+BaseUuidTest.ancestors.include?(Familia::Base)
+#=> true
+
+## Feature methods are accessible through the class
+BaseUuidTest.respond_to?(:feature)
+#=> true
+
+## Class instance variables are properly initialized
+BaseUuidTest.instance_variable_get(:@fields)
+#=:> Array
+
+## Field definitions are properly initialized
+BaseUuidTest.instance_variable_get(:@field_types)
+#=:> Hash
+
+## Feature system is properly integrated
+BaseUuidTest.respond_to?(:feature)
+#=> true
+
+## Feature registration methods are available
+Familia::Base.respond_to?(:add_feature)
+#=> true
+
+## Valid identifiers work correctly
+@base_uuid.identifier
+#=> "uuid_test_1"
+
+## Empty class has base methods available
+EmptyBaseTest.ancestors.include?(Familia::Base)
+#=> true
+
+## Empty class can use feature system
+EmptyBaseTest.respond_to?(:feature)
+#=> true
+
+## Test Base module constants are defined
+Familia::Base.features_available
+#=:> Hash
+
+## Dump and load methods are set
+Familia::Base.dump_method
+#=> :to_json
+
+## Load method is set correctly
+Familia::Base.load_method
+#=> :from_json
+
+## Base module provides inspect with class name
+@base_uuid.inspect.include?('BaseUuidTest')
+#=> true
+
+@base_uuid.destroy! rescue nil
+@base_uuid2.destroy! rescue nil
+@base_uuid = nil
+@base_uuid2 = nil

data/try/core/connection_try.rb

@@ -1,6 +1,5 @@
 # try/core/connection_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false

data/try/core/errors_try.rb

@@ -1,6 +1,5 @@
 # try/core/errors_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false

data/try/core/familia_extended_try.rb

@@ -2,7 +2,6 @@
 
 require 'time'
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 ## Has all datatype relativess
@@ -11,15 +10,15 @@ registered_types.collect(&:to_s).sort
 #=> ["counter", "hash", "hashkey", "list", "lock", "set", "sorted_set", "string", "zset"]
 
 ## Familia created class methods for datatype list class
-Familia::Horreum::ClassMethods.public_method_defined? :list?
+Familia::Horreum::DefinitionMethods.public_method_defined? :list?
 #=> true
 
 ## Familia created class methods for datatype list class
-Familia::Horreum::ClassMethods.public_method_defined? :list
+Familia::Horreum::DefinitionMethods.public_method_defined? :list
 #=> true
 
 ## Familia created class methods for datatype list class
-Familia::Horreum::ClassMethods.public_method_defined? :lists
+Familia::Horreum::DefinitionMethods.public_method_defined? :lists
 #=> true
 
 ## A Familia object knows its datatype relatives

data/try/core/familia_try.rb

@@ -1,6 +1,5 @@
 # try/core/familia_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 ## Check for help class

data/try/core/pools_try.rb

@@ -30,7 +30,7 @@ end
 class PoolTestAccount < Familia::Horreum
   identifier_field :account_id
   field :account_id
-  field :balance
+  field :balance, on_conflict: :skip
   field :holder_name
 
   def init
@@ -83,7 +83,7 @@ class PoolTestAccountDB1 < Familia::Horreum
   self.logical_database = 1
   identifier_field :account_id
   field :account_id
-  field :balance
+  field :balance, on_conflict: :skip
   field :holder_name
 
   def init

data/try/core/secure_identifier_try.rb

@@ -2,7 +2,6 @@
 
 # Test Familia::SecureIdentifier methods
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false

data/try/core/settings_try.rb

@@ -1,6 +1,5 @@
 # try/core/settings_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false

data/try/core/utils_try.rb

@@ -1,6 +1,5 @@
 # try/core/utils_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false

data/try/{datatypes → data_types}/boolean_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/boolean_try.rb
+# try/data_types/boolean_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 Familia.debug = false

data/try/{datatypes → data_types}/datatype_base_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/base_try.rb
+# try/data_types/base_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 @limiter1 = Limiter.new :requests
@@ -64,6 +63,6 @@ p [@limiter1.counter.parent.default_expiration, @limiter2.counter.parent.default
 #=> 3600.0
 
 ## Check current_expiration
-sleep 1 # Database default_expirations are in seconds so we can't wait any less time than this (without mocking)
+sleep 1 # NOTE: Mocking time would be foolish in life, but helpful here
 @limiter1.counter.current_expiration
 #=> 3600-1

data/try/{datatypes → data_types}/hash_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/hash_try.rb
+# try/data_types/hash_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 @a = Bone.new 'atoken'

data/try/{datatypes → data_types}/list_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/list_try.rb
+# try/data_types/list_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 @a = Bone.new 'atoken'

data/try/{datatypes → data_types}/set_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/set_try.rb
+# try/data_types/set_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 @a = Bone.new 'atoken'

data/try/{datatypes → data_types}/sorted_set_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/sorted_set_try.rb
+# try/data_types/sorted_set_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 @a = Bone.new 'atoken'

data/try/{datatypes → data_types}/string_try.rb

@@ -1,6 +1,5 @@
-# try/datatypes/string_try.rb
+# try/data_types/string_try.rb
 
-require_relative '../../lib/familia'
 require_relative '../helpers/test_helpers'
 
 @a = Bone.new(token: 'atoken2')

data/try/debugging/README.md

@@ -0,0 +1,32 @@
+# Familia Encryption Debugging Tools
+
+Debug scripts for encryption issues. All scripts run safely without modifying data.
+
+## Quick Reference
+
+| Issue | Script | Purpose |
+|-------|--------|---------|
+| Provider problems | `provider_diagnostics.rb` | Test provider registration, availability, compatibility |
+| Performance issues | `cache_behavior_tracer.rb` | Analyze key derivation cache efficiency |
+| Field operations | `encryption_method_tracer.rb` | Trace encrypt/decrypt calls with timing |
+
+```bash
+# Run any script
+ruby try/debugging/[script_name].rb
+```
+
+## Usage Guide
+
+**Provider Issues**: Algorithm not found, registration failures
+→ `provider_diagnostics.rb`
+
+**Slow Performance**: Excessive key derivations, cache misses
+→ `cache_behavior_tracer.rb` then `encryption_method_tracer.rb`
+
+**Field Bugs**: AAD problems, context issues, decryption failures
+→ `encryption_method_tracer.rb`
+
+## Output Key
+- **SUCCESS/FAILED/ERROR** = test results
+- `version:context => [bytes]` = cache entries
+- Timing in milliseconds = performance data

data/try/debugging/cache_behavior_tracer.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# Debug script to trace encryption cache behavior and key derivation
+
+require 'base64'
+require 'bundler/setup'
+require_relative '../helpers/test_helpers'
+
+puts "=== Encryption Cache Behavior Tracer ==="
+puts
+
+# Setup test configuration
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+# Clear any existing cache
+Thread.current[:familia_key_cache] = nil
+puts "1. Initial Cache State:"
+puts "   Cache: #{Thread.current[:familia_key_cache].inspect}"
+puts
+
+# Define test model with multiple encrypted fields
+class CacheTraceModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :user_id
+
+  field :user_id
+  encrypted_field :field_a
+  encrypted_field :field_b
+  encrypted_field :field_c
+end
+
+puts "2. Model Creation:"
+user = CacheTraceModel.new(user_id: 'cache-user-1')
+puts "   After model creation: #{Thread.current[:familia_key_cache].inspect}"
+puts
+
+puts "3. Setting Encrypted Fields:"
+['field_a', 'field_b', 'field_c'].each_with_index do |field, i|
+  puts "   Setting #{field}..."
+  user.public_send("#{field}=", "test-value-#{i+1}")
+  cache = Thread.current[:familia_key_cache]
+  if cache
+    puts "     Cache size: #{cache.size}"
+    puts "     Cache keys: #{cache.keys.inspect}"
+  else
+    puts "     Cache: nil"
+  end
+end
+puts
+
+puts "4. Reading Encrypted Fields:"
+['field_a', 'field_b', 'field_c'].each do |field|
+  puts "   Reading #{field}..."
+  value = user.public_send(field)
+  puts "     Retrieved: #{value}"
+  cache = Thread.current[:familia_key_cache]
+  if cache
+    puts "     Cache size: #{cache.size}"
+    puts "     Cache keys: #{cache.keys.inspect}"
+  else
+    puts "     Cache: nil"
+  end
+end
+puts
+
+puts "5. Final Cache Analysis:"
+cache = Thread.current[:familia_key_cache]
+if cache && !cache.empty?
+  puts "   Cache size: #{cache.size} entries"
+  cache.each_with_index do |(key, value), i|
+    puts "   Entry #{i+1}: #{key} => [#{value.bytesize} bytes]"
+  end
+else
+  puts "   Cache is empty or nil"
+end
+puts
+
+# Test cache behavior with multiple models
+puts "6. Multiple Models Cache Test:"
+user2 = CacheTraceModel.new(user_id: 'cache-user-2')
+user2.field_a = 'different-value'
+puts "   After second model field set:"
+cache = Thread.current[:familia_key_cache]
+if cache
+  puts "     Cache size: #{cache.size}"
+  puts "     Unique contexts: #{cache.keys.map { |k| k.split(':').last }.uniq.size}"
+end
+
+puts
+puts "=== Cache Tracing Complete ==="

data/try/debugging/encryption_method_tracer.rb

@@ -0,0 +1,138 @@
+#!/usr/bin/env ruby
+# Debug script to trace encryption method calls and data flow
+
+require 'base64'
+require 'bundler/setup'
+require_relative '../helpers/test_helpers'
+
+puts "=== Encryption Method Call Tracer ==="
+puts
+
+# Monkey patch to add detailed tracing
+module Familia
+  module Encryption
+    class << self
+      # Store original methods
+      alias_method :orig_encrypt, :encrypt
+      alias_method :orig_decrypt, :decrypt
+
+      def encrypt(plaintext, context:, additional_data: nil)
+        puts "📤 ENCRYPT called:"
+        puts "   Context: #{context}"
+        puts "   Plaintext length: #{plaintext&.length} chars"
+        puts "   AAD: #{additional_data ? 'present' : 'none'}"
+
+        start_time = Time.now
+        result = orig_encrypt(plaintext, context: context, additional_data: additional_data)
+        elapsed = ((Time.now - start_time) * 1000).round(2)
+
+        puts "   Result length: #{result ? result.length : 'nil'} chars"
+        puts "   Elapsed: #{elapsed}ms"
+        puts
+        result
+      end
+
+      def decrypt(encrypted_json, context:, additional_data: nil)
+        puts "📥 DECRYPT called:"
+        puts "   Context: #{context}"
+        puts "   Encrypted length: #{encrypted_json&.length} chars"
+        puts "   AAD: #{additional_data ? 'present' : 'none'}"
+
+        start_time = Time.now
+        begin
+          result = orig_decrypt(encrypted_json, context: context, additional_data: additional_data)
+          elapsed = ((Time.now - start_time) * 1000).round(2)
+
+          puts "   Result length: #{result ? result.length : 'nil'} chars"
+          puts "   Elapsed: #{elapsed}ms"
+          puts
+          result
+        rescue => e
+          elapsed = ((Time.now - start_time) * 1000).round(2)
+          puts "   ERROR: #{e.class}: #{e.message}"
+          puts "   Elapsed: #{elapsed}ms"
+          puts
+          raise
+        end
+      end
+    end
+
+    class Manager
+      alias_method :orig_derive_key_with_provider, :derive_key_with_provider
+
+      def derive_key_with_provider(provider, context, version: nil)
+        puts "🔑 DERIVE_KEY called:"
+        puts "   Provider: #{provider.class.name}"
+        puts "   Context: #{context}"
+        puts "   Version: #{version || 'current'}"
+
+        cache = Thread.current[:familia_key_cache] ||= {}
+        cache_key = "#{version || current_key_version}:#{context}"
+        puts "   Cache key: #{cache_key}"
+        puts "   Cache before: #{cache.keys.inspect}"
+
+        start_time = Time.now
+        result = orig_derive_key_with_provider(provider, context, version: version)
+        elapsed = ((Time.now - start_time) * 1000).round(2)
+
+        cache_after = Thread.current[:familia_key_cache] || {}
+        puts "   Cache after: #{cache_after.keys.inspect}"
+        puts "   Derived key: [#{result.bytesize} bytes]"
+        puts "   Elapsed: #{elapsed}ms"
+        puts
+        result
+      end
+    end
+  end
+end
+
+# Setup test configuration
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+# Clear cache
+Thread.current[:familia_key_cache] = nil
+
+# Define test model
+class TraceTestModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :user_id
+
+  field :user_id
+  encrypted_field :password
+  encrypted_field :api_key, aad_fields: [:user_id]
+end
+
+puts "=== Test Scenario: Field Operations ==="
+puts
+
+puts "Creating model and setting encrypted fields..."
+user = TraceTestModel.new(user_id: 'trace-user-1')
+
+puts "Setting password (no AAD)..."
+user.password = 'secret-password-123'
+
+puts "Setting api_key (with AAD)..."
+user.api_key = 'api-key-xyz-789'
+
+puts "Reading password..."
+retrieved_password = user.password
+puts "Final password value: #{retrieved_password}"
+
+puts "Reading api_key..."
+retrieved_api_key = user.api_key
+puts "Final api_key value: #{retrieved_api_key}"
+
+puts
+puts "=== Test Scenario: Cross-Algorithm Decryption ==="
+puts
+
+# Test cross-algorithm compatibility
+aes_encrypted = Familia::Encryption.encrypt_with('aes-256-gcm', 'cross-test-data', context: 'cross-test')
+puts "Decrypting AES-GCM data with default manager..."
+cross_decrypted = Familia::Encryption.decrypt(aes_encrypted, context: 'cross-test')
+puts "Cross-algorithm result: #{cross_decrypted}"
+
+puts
+puts "=== Method Tracing Complete ==="