familia 2.0.0.pre4 → 2.0.0.pre6

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/debug_aad_process.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Debugging AAD during encrypt/decrypt process..."
+
+# Setup encryption keys
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class DebugModelA < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+class DebugModelB < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+# Patch the EncryptedFieldType to add debug output
+class Familia::EncryptedFieldType
+  alias_method :original_encrypt_value, :encrypt_value
+  alias_method :original_decrypt_value, :decrypt_value
+  alias_method :original_build_aad, :build_aad
+
+  def encrypt_value(record, value)
+    context = build_context(record)
+    aad = build_aad(record)
+    puts "[ENCRYPT] Class: #{record.class}, ID: #{record.identifier}, Context: #{context}, AAD: #{aad}"
+    original_encrypt_value(record, value)
+  end
+
+  def decrypt_value(record, encrypted)
+    context = build_context(record)
+    aad = build_aad(record)
+    puts "[DECRYPT] Class: #{record.class}, ID: #{record.identifier}, Context: #{context}, AAD: #{aad}"
+    original_decrypt_value(record, encrypted)
+  end
+
+  def build_aad(record)
+    aad = original_build_aad(record)
+    puts "[BUILD_AAD] Class: #{record.class}, ID: #{record.identifier}, AAD: #{aad}"
+    aad
+  end
+end
+
+# Clean database
+Familia.dbclient.flushdb
+
+model_a = DebugModelA.new(id: 'same-id')
+model_b = DebugModelB.new(id: 'same-id')
+
+puts "\n=== ENCRYPTION PHASE ==="
+puts "Encrypting for ModelA:"
+model_a.api_key = 'secret-key'
+cipher_a = model_a.instance_variable_get(:@api_key)
+
+puts "\nEncrypting for ModelB:"
+model_b.api_key = 'secret-key'
+cipher_b = model_b.instance_variable_get(:@api_key)
+
+puts "\n=== DECRYPTION PHASE - Same Context ==="
+puts "Decrypting ModelA with ModelA context:"
+model_a.api_key.reveal { |plain| puts "Result: #{plain}" }
+
+puts "\n=== DECRYPTION PHASE - Cross Context ==="
+puts "Setting ModelB cipher into ModelA and trying to decrypt:"
+model_a.instance_variable_set(:@api_key, cipher_b)
+begin
+  model_a.api_key.reveal { |plain| puts "ERROR: Cross-context worked: #{plain}" }
+rescue => e
+  puts "SUCCESS: Cross-context failed as expected: #{e.class}: #{e.message}"
+end

data/try/debugging/debug_concealed_internal.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'  # Mark as test environment
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Testing ConcealedString internal call chain..."
+
+class TestModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :secret
+end
+
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+# Clean database
+Familia.dbclient.flushdb
+
+puts "\n=== CONCEALED STRING INTERNAL DEBUGGING ==="
+
+# Create and save model
+model = TestModel.new(id: 'test1')
+model.secret = 'plaintext-secret'
+model.save
+
+# Load model from database
+loaded_model = TestModel.load('test1')
+concealed_string = loaded_model.secret
+
+# Access internal ConcealedString components
+puts "ConcealedString @encrypted_data: #{concealed_string.instance_variable_get(:@encrypted_data)}"
+puts "ConcealedString @record: #{concealed_string.instance_variable_get(:@record)}"
+puts "ConcealedString @field_type: #{concealed_string.instance_variable_get(:@field_type)}"
+
+record = concealed_string.instance_variable_get(:@record)
+field_type = concealed_string.instance_variable_get(:@field_type)
+encrypted_data = concealed_string.instance_variable_get(:@encrypted_data)
+
+puts "\n=== STEP BY STEP DECRYPTION ==="
+puts "Record class: #{record.class}"
+puts "Record identifier: #{record.identifier}"
+puts "Record exists?: #{record.exists?}"
+puts "Field type class: #{field_type.class}"
+
+# Test the exact same call that ConcealedString.reveal makes
+puts "\nCalling field_type.decrypt_value(record, encrypted_data)..."
+begin
+  result = field_type.decrypt_value(record, encrypted_data)
+  puts "decrypt_value result: #{result}"
+  puts "Result class: #{result.class}"
+rescue => e
+  puts "decrypt_value ERROR: #{e.class}: #{e.message}"
+  puts e.backtrace.first(10)
+end

data/try/debugging/debug_concealed_reveal.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'  # Mark as test environment
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Testing ConcealedString.reveal error handling..."
+
+class TestModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :secret
+end
+
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+# Clean database
+Familia.dbclient.flushdb
+
+puts "\n=== CONCEALED STRING REVEAL ERROR PATH ==="
+
+# Create and save model (encrypt with AAD = nil)
+model = TestModel.new(id: 'test1')
+model.secret = 'plaintext-secret'
+model.save
+
+# Load model from database (decrypt with AAD = "test1")
+loaded_model = TestModel.load('test1')
+
+puts "Loaded model secret class: #{loaded_model.secret.class}"
+
+# Test ConcealedString.reveal directly
+concealed_string = loaded_model.secret
+puts "ConcealedString object: #{concealed_string.inspect}"
+
+puts "\nTesting ConcealedString.reveal..."
+begin
+  result = concealed_string.reveal do |plaintext|
+    puts "Inside reveal block, plaintext: #{plaintext}"
+    plaintext  # Return the plaintext
+  end
+  puts "Reveal result: #{result}"
+  puts "Result class: #{result.class}"
+rescue => e
+  puts "Reveal ERROR: #{e.class}: #{e.message}"
+  puts e.backtrace.first(5)
+end
+
+puts "\nTesting ConcealedString.reveal_for_testing..."
+begin
+  result = concealed_string.reveal_for_testing
+  puts "reveal_for_testing result: #{result}"
+  puts "Result class: #{result.class}"
+rescue => e
+  puts "reveal_for_testing ERROR: #{e.class}: #{e.message}"
+  puts e.backtrace.first(5)
+end

data/try/debugging/debug_context_aad.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Debugging context and AAD generation..."
+
+# Setup encryption keys
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class ModelA < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+class ModelB < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+model_a = ModelA.new(id: 'same-id')
+model_b = ModelB.new(id: 'same-id')
+
+# Get the field type for each model
+field_type_a = ModelA.fields[:api_key]
+field_type_b = ModelB.fields[:api_key]
+
+puts "=== Context and AAD Analysis ==="
+
+# Test context generation
+context_a = field_type_a.send(:build_context, model_a)
+context_b = field_type_b.send(:build_context, model_b)
+
+puts "ModelA context: #{context_a}"
+puts "ModelB context: #{context_b}"
+puts "Contexts match: #{context_a == context_b}"
+
+# Test AAD generation
+aad_a = field_type_a.send(:build_aad, model_a)
+aad_b = field_type_b.send(:build_aad, model_b)
+
+puts "\nModelA AAD: #{aad_a}"
+puts "ModelB AAD: #{aad_b}"
+puts "AADs match: #{aad_a == aad_b}"
+
+puts "\n=== Testing different identifiers ==="
+model_a2 = ModelA.new(id: 'different-id')
+model_b2 = ModelB.new(id: 'different-id')
+
+context_a2 = field_type_a.send(:build_context, model_a2)
+context_b2 = field_type_b.send(:build_context, model_b2)
+aad_a2 = field_type_a.send(:build_aad, model_a2)
+aad_b2 = field_type_b.send(:build_aad, model_b2)
+
+puts "ModelA2 context: #{context_a2}"
+puts "ModelB2 context: #{context_b2}"
+puts "A2-B2 contexts match: #{context_a2 == context_b2}"
+puts "ModelA2 AAD: #{aad_a2}"
+puts "ModelB2 AAD: #{aad_b2}"
+puts "A2-B2 AADs match: #{aad_a2 == aad_b2}"

data/try/debugging/debug_context_simple.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'
+require 'familia'
+
+puts "Understanding the issue with cross-context decryption..."
+
+# Setup encryption keys
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class ModelA < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+class ModelB < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+model_a = ModelA.new(id: 'same-id')
+model_b = ModelB.new(id: 'same-id')
+
+puts "ModelA class: #{model_a.class}"
+puts "ModelB class: #{model_b.class}"
+puts "Same class?: #{model_a.class == model_b.class}"
+
+# Inspect what context would be built
+puts "\nContext analysis:"
+puts "ModelA identifier: #{model_a.identifier}"
+puts "ModelB identifier: #{model_b.identifier}"
+
+# Let's see what happens with the field types
+modelA_api_key_type = nil
+modelB_api_key_type = nil
+
+ModelA.field_types.each do |name, type|
+  if name == :api_key
+    modelA_api_key_type = type
+    break
+  end
+end
+
+ModelB.field_types.each do |name, type|
+  if name == :api_key
+    modelB_api_key_type = type
+    break
+  end
+end
+
+puts "ModelA api_key type: #{modelA_api_key_type}"
+puts "ModelB api_key type: #{modelB_api_key_type}"
+puts "Same type object?: #{modelA_api_key_type.object_id == modelB_api_key_type.object_id}"
+
+# Check what context and AAD would be generated
+if modelA_api_key_type && modelB_api_key_type
+  context_a = "#{model_a.class.name}:api_key:#{model_a.identifier}"
+  context_b = "#{model_b.class.name}:api_key:#{model_b.identifier}"
+
+  puts "\nExpected contexts:"
+  puts "ModelA context: #{context_a}"
+  puts "ModelB context: #{context_b}"
+  puts "Contexts should be different: #{context_a != context_b}"
+
+  # AAD should be identifier when no aad_fields
+  aad_a = model_a.identifier
+  aad_b = model_b.identifier
+
+  puts "\nExpected AADs:"
+  puts "ModelA AAD: #{aad_a}"
+  puts "ModelB AAD: #{aad_b}"
+  puts "AADs are same: #{aad_a == aad_b}"
+end

data/try/debugging/debug_cross_context.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Debugging cross-context validation..."
+
+# Setup encryption keys
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class ModelA < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+class ModelB < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :api_key
+end
+
+# Clean database
+Familia.dbclient.flushdb
+
+model_a = ModelA.new(id: 'same-id')
+model_b = ModelB.new(id: 'same-id')
+
+model_a.api_key = 'secret-key'
+model_b.api_key = 'secret-key'
+
+cipher_a = model_a.instance_variable_get(:@api_key)
+cipher_b = model_b.instance_variable_get(:@api_key)
+
+puts "cipher_a: #{cipher_a.class} - #{cipher_a.encrypted_value}"
+puts "cipher_b: #{cipher_b.class} - #{cipher_b.encrypted_value}"
+
+# Now try cross-context access
+puts "\n=== Cross-context test ==="
+model_a.instance_variable_set(:@api_key, cipher_b)
+puts "Set cipher_b into model_a"
+
+begin
+  result = model_a.api_key
+  puts "Got result: #{result.class} - should be ConcealedString"
+
+  # Try to reveal it
+  result.reveal do |plaintext|
+    puts "Successfully revealed: #{plaintext}"
+  end
+  puts "ERROR: Cross-context decryption should have failed!"
+rescue Familia::EncryptionError => e
+  puts "SUCCESS: Got expected encryption error: #{e.message}"
+rescue => e
+  puts "Got unexpected error: #{e.class}: #{e.message}"
+end

data/try/debugging/debug_database_load.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'  # Mark as test environment
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Testing database load vs in-memory encryption..."
+
+class TestModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  field :title
+  encrypted_field :secret
+end
+
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+# Clean database
+Familia.dbclient.flushdb
+
+puts "\n=== PHASE 1: In-memory object ==="
+model = TestModel.new(id: 'test1')
+model.title = 'Test Title'
+puts "PRE-ENCRYPT: model.exists? = #{model.exists?}"
+model.secret = 'plaintext-secret'
+
+puts "In-memory secret class: #{model.secret.class}"
+puts "In-memory secret value: #{model.secret}"
+
+model.secret.reveal do |plaintext|
+  puts "In-memory reveal: #{plaintext}"
+end
+
+puts "\n=== PHASE 2: Save to database ==="
+model.save
+
+puts "Keys in database: #{Familia.dbclient.keys('*')}"
+puts "Hash contents: #{Familia.dbclient.hgetall('testmodel:test1:object')}"
+
+raw_secret = Familia.dbclient.hget('testmodel:test1:object', 'secret')
+puts "Raw secret from DB: #{raw_secret}"
+
+puts "\n=== PHASE 3: Load from database ==="
+loaded_model = TestModel.load('test1')
+
+if loaded_model
+  puts "Loaded model exists: #{loaded_model.exists?}"
+  puts "Loaded secret class: #{loaded_model.secret.class}"
+  puts "Loaded secret value: #{loaded_model.secret}"
+
+  begin
+    loaded_model.secret.reveal do |plaintext|
+      puts "Loaded reveal: #{plaintext}"
+    end
+  rescue => e
+    puts "Loaded reveal ERROR: #{e.class}: #{e.message}"
+  end
+else
+  puts "Failed to load model"
+end

data/try/debugging/debug_encrypted_json_check.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('lib', __dir__))
+ENV['TEST'] = 'true'  # Mark as test environment
+require 'familia'
+require_relative 'try/helpers/test_helpers'
+
+puts "Testing encrypted_json? method..."
+
+class TestModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :secret
+end
+
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+field_type = TestModel.field_types[:secret]
+
+# Test with actual encrypted JSON from the load path
+encrypted_json = '{"algorithm":"xchacha20poly1305","nonce":"RDK0GSY3Vbrbv7OAgol10bHOmderAExt","ciphertext":"uo8j6Pm6tV68BcvqK5maXQ==","auth_tag":"5Cr1QgTnajnWIji0fsQP0g==","key_version":"v1"}'
+
+puts "Testing encrypted JSON: #{encrypted_json[0..80]}..."
+puts "String class: #{encrypted_json.class}"
+puts "Is string?: #{encrypted_json.is_a?(String)}"
+
+puts "\nManual JSON parsing:"
+begin
+  parsed = JSON.parse(encrypted_json)
+  puts "Parsed successfully: #{parsed.class}"
+  puts "Is hash?: #{parsed.is_a?(Hash)}"
+  puts "Has algorithm key?: #{parsed.key?('algorithm')}"
+  puts "Algorithm value: #{parsed['algorithm']}"
+rescue => e
+  puts "JSON parse error: #{e.class}: #{e.message}"
+end
+
+puts "\nTesting field_type.encrypted_json? method:"
+result = field_type.encrypted_json?(encrypted_json)
+puts "encrypted_json? result: #{result}"
+
+puts "\nTesting with symbol keys:"
+begin
+  parsed_sym = JSON.parse(encrypted_json, symbolize_names: true)
+  puts "Parsed with symbols: #{parsed_sym.class}"
+  puts "Has :algorithm key?: #{parsed_sym.key?(:algorithm)}"
+  puts "Has 'algorithm' key?: #{parsed_sym.key?('algorithm')}"
+rescue => e
+  puts "Symbol parse error: #{e.class}: #{e.message}"
+end