familia 2.0.0.pre14 → 2.0.0.pre16

data/lib/familia/features/encrypted_fields.rb

@@ -5,7 +5,7 @@ require_relative 'encrypted_fields/encrypted_field_type'
 module Familia
   module Features
     # EncryptedFields is a feature that provides transparent encryption and decryption
-    # of sensitive data stored in Redis/Valkey. It uses strong cryptographic algorithms
+    # of sensitive data stored in Valkey/Redis. It uses strong cryptographic algorithms
     # with field-specific key derivation to protect data at rest while maintaining
     # easy access patterns for authorized applications.
     #
@@ -46,7 +46,7 @@ module Familia
     # Security Features:
     #
     # Each encrypted field uses a unique encryption key derived from:
-    # - Master encryption key (from Familia.encryption_key)
+    # - Master encryption key (from Familia.encryption_keys[current_key_version])
     # - Field name (cryptographic domain separation)
     # - Record identifier (per-record key derivation)
     # - Class name (per-class key derivation)
@@ -97,27 +97,22 @@ module Familia
     #   # The content can only be decrypted if doc_id, owner_id, and classification
     #   # values match those used during encryption
     #
-    # Passphrase Protection:
+    # Request-Level Caching:
     #
-    # For ultra-sensitive fields, require user passphrases for decryption:
+    # For performance optimization, enable key derivation caching per request:
     #
-    #   class PersonalVault < Familia::Horreum
-    #     feature :encrypted_fields
-    #
-    #     field :user_id
-    #     encrypted_field :diary_entry    # Ultra-sensitive
-    #     encrypted_field :photos         # Ultra-sensitive
+    #   Familia::Encryption.with_request_cache do
+    #     vault.secret_key = "value1"
+    #     vault.api_token = "value2"
+    #     vault.save  # Reuses derived keys within this block
     #   end
     #
-    #   vault = PersonalVault.new(user_id: 123, diary_entry: "Dear diary...")
-    #   vault.save
-    #
-    #   # Passphrase required for decryption
-    #   diary = vault.diary_entry(passphrase_value: user_passphrase)
+    #   # Cache is automatically cleared when block exits
+    #   # Or manually: Familia::Encryption.clear_request_cache!
     #
-    # Memory Safety:
+    # Preventing Accidental Leakage:
     #
-    # Encrypted fields return ConcealedString objects that provide memory protection:
+    # Encrypted fields return ConcealedString objects to help prevent exposure.
     #
     #   secret = vault.secret_key
     #   secret.class               # => ConcealedString
@@ -125,13 +120,11 @@ module Familia
     #   secret.inspect             # => "[CONCEALED]" (automatic redaction)
     #
     #   # Safe access pattern
-    #   secret.expose do |value|
-    #     # Use value directly without creating copies
-    #     api_call(authorization: "Bearer #{value}")
-    #   end
+    #   raw_value = secret.reveal  # Returns actual decrypted string
+    #   # Use raw_value carefully - avoid creating copies
     #
-    #   # Direct access (use carefully)
-    #   raw_value = secret.value   # Returns actual decrypted string
+    #   # Check if cleared from memory available to Ruby runtime process.
+    #   secret.cleared?            # Returns true if wiped
     #
     #   # Explicit cleanup
     #   secret.clear!              # Best-effort memory wiping
@@ -143,41 +136,51 @@ module Familia
     #   # Invalid ciphertext or tampering
     #   vault.secret_key  # => Familia::EncryptionError: Authentication failed
     #
-    #   # Wrong passphrase
-    #   vault.diary_entry(passphrase_value: "wrong")
-    #   # => Familia::EncryptionError: Invalid passphrase
+    #   # Missing encryption configuration
+    #   Familia.config.encryption_keys = {}
+    #   vault.secret_key  # => Familia::EncryptionError: No encryption keys configured
     #
-    #   # Missing encryption key
-    #   Familia.encryption_key = nil
-    #   vault.secret_key  # => Familia::EncryptionError: No encryption key configured
+    #   # Invalid key version
+    #   # Key exists in storage but not in current configuration
+    #   vault.secret_key  # => Familia::EncryptionError: Key version not found: v1
     #
     # Configuration:
     #
-    #   # Set master encryption key (required)
+    #   # Configure versioned encryption keys (required)
     #   Familia.configure do |config|
-    #     config.encryption_key = ENV['FAMILIA_ENCRYPTION_KEY']
-    #     config.encryption_personalization = 'MyApp-2024'  # Optional customization
+    #     config.encryption_keys = {
+    #       v1: ENV['FAMILIA_ENCRYPTION_KEY'],
+    #       v2: ENV['FAMILIA_ENCRYPTION_KEY_V2']
+    #     }
+    #     config.current_key_version = :v2
+    #     config.encryption_personalization = 'MyApp-2024'  # Optional (XChaCha20 only)
     #   end
     #
-    #   # Generate a new encryption key
-    #   key = Familia::Encryption.generate_key
-    #   puts key  # => "base64-encoded-32-byte-key"
+    #   # Validate configuration before use
+    #   Familia::Encryption.validate_configuration!
     #
     # Key Rotation:
     #
     # The feature supports key versioning for seamless key rotation:
     #
-    #   # Step 1: Add new key while keeping old key
+    #   # Step 1: Add new key version while keeping old keys
     #   Familia.configure do |config|
-    #     config.encryption_key = new_key
-    #     config.legacy_encryption_keys = { 'v1' => old_key }
+    #     config.encryption_keys = {
+    #       v1: old_key,
+    #       v2: new_key
+    #     }
+    #     config.current_key_version = :v2
     #   end
     #
-    #   # Step 2: Objects decrypt with old key, encrypt with new key
-    #   vault.secret_key = "new-secret"  # Encrypted with new key
+    #   # Step 2: Objects decrypt with any valid key, encrypt with current key
+    #   vault.secret_key = "new-secret"  # Encrypted with v2 key
+    #   vault.save
+    #
+    #   # Step 3: Re-encrypt existing records
+    #   vault.re_encrypt_fields!  # Uses current key version
     #   vault.save
     #
-    #   # Step 3: After all data is re-encrypted, remove legacy key
+    #   # Step 4: After all data is re-encrypted, remove old key
     #
     # Integration Patterns:
     #
@@ -208,10 +211,9 @@ module Familia
     #       user = User.find(user_id)
     #
     #       # Access encrypted field safely
-    #       user.credit_card_number.expose do |cc_number|
-    #         # Process payment without storing plaintext
-    #         payment_gateway.charge(cc_number, amount)
-    #       end
+    #       cc_number = user.credit_card_number.reveal
+    #       # Process payment without storing plaintext
+    #       payment_gateway.charge(cc_number, amount)
     #
     #       # Clear sensitive data from memory
     #       user.credit_card_number.clear!
@@ -221,10 +223,12 @@ module Familia
     # Performance Considerations:
     #
     # - Encryption/decryption adds ~1-5ms overhead per field
-    # - Key derivation is cached per field/record combination
+    # - Key derivation is NOT cached by default for security
+    # - Use request-level caching for performance: with_request_cache { ... }
     # - XChaCha20-Poly1305 is ~2x faster than AES-256-GCM
     # - Memory allocation increases due to ciphertext expansion
     # - Consider batching operations for high-throughput scenarios
+    # - Personalization only affects XChaCha20-Poly1305 BLAKE2b derivation
     #
     # Security Limitations:
     #
@@ -255,15 +259,17 @@ module Familia
     # - Insider threats with application access
     #
     module EncryptedFields
+      Familia::Base.add_feature self, :encrypted_fields
+
       def self.included(base)
-        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-        base.extend ClassMethods
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
 
         # Initialize encrypted fields tracking
         base.instance_variable_set(:@encrypted_fields, []) unless base.instance_variable_defined?(:@encrypted_fields)
       end
 
-      module ClassMethods
+      module ModelClassMethods
         # Define an encrypted field that transparently encrypts/decrypts values
         #
         # Encrypted fields are stored as JSON objects containing the encrypted
@@ -287,13 +293,13 @@ module Familia
         #     encrypted_field :content, aad_fields: [:doc_id, :owner_id]
         #   end
         #
-        def encrypted_field(name, aad_fields: [], **kwargs)
+        def encrypted_field(name, aad_fields: [], **)
           @encrypted_fields ||= []
           @encrypted_fields << name unless @encrypted_fields.include?(name)
 
           require_relative 'encrypted_fields/encrypted_field_type'
 
-          field_type = EncryptedFieldType.new(name, aad_fields: aad_fields, **kwargs)
+          field_type = EncryptedFieldType.new(name, aad_fields: aad_fields, **)
           register_field_type(field_type)
         end
 
@@ -324,7 +330,7 @@ module Familia
             algorithm: provider.algorithm_name,
             key_size: provider.key_size,
             nonce_size: provider.nonce_size,
-            tag_size: provider.tag_size
+            tag_size: provider.tag_size,
           }
         end
       end
@@ -357,9 +363,7 @@ module Familia
       def clear_encrypted_fields!
         self.class.encrypted_fields.each do |field_name|
           field_value = instance_variable_get("@#{field_name}")
-          if field_value.respond_to?(:clear!)
-            field_value.clear!
-          end
+          field_value.clear! if field_value.respond_to?(:clear!)
         end
       end
 
@@ -419,19 +423,17 @@ module Familia
         self.class.encrypted_fields.each_with_object({}) do |field_name, status|
           field_value = instance_variable_get("@#{field_name}")
 
-          if field_value.nil?
-            status[field_name] = { encrypted: false, value: nil }
-          elsif field_value.respond_to?(:cleared?) && field_value.cleared?
-            status[field_name] = { encrypted: true, cleared: true }
-          elsif field_value.respond_to?(:concealed?) && field_value.concealed?
-            status[field_name] = { encrypted: true, algorithm: "unknown", cleared: false }
-          else
-            status[field_name] = { encrypted: false, value: "[CONCEALED]" }
-          end
+          status[field_name] = if field_value.nil?
+                                 { encrypted: false, value: nil }
+                               elsif field_value.respond_to?(:cleared?) && field_value.cleared?
+                                 { encrypted: true, cleared: true }
+                               elsif field_value.respond_to?(:concealed?) && field_value.concealed?
+                                 { encrypted: true, algorithm: 'unknown', cleared: false }
+                               else
+                                 { encrypted: false, value: '[CONCEALED]' }
+                               end
         end
       end
-
-      Familia::Base.add_feature self, :encrypted_fields
     end
   end
 end

data/lib/familia/features/expiration/extensions.rb

@@ -0,0 +1,61 @@
+# lib/familia/features/expiration/extensions.rb
+
+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.
+    #
+    # This is a no-op implementation that gets overridden by the :expiration
+    # feature. It accepts an optional default_expiration parameter to maintain
+    # interface compatibility with the overriding implementations.
+    #
+    # @param default_expiration [Numeric, nil] Time To Live in seconds
+    # @return [nil] Always returns nil for the base implementation
+    #
+    # @note This is a no-op implementation. Classes that need expiration
+    #       functionality should include the :expiration feature.
+    #
+    # @example Enable expiration feature
+    #   class MyModel < Familia::Horreum
+    #     feature :expiration
+    #     default_expiration 1.hour
+    #   end
+    #
+    def update_expiration(default_expiration: nil)
+      Familia.ld <<~LOG
+        [update_expiration] Expiration feature not enabled for #{self.class}.
+        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
+      LOG
+      nil
+    end
+
+    # Base implementation of ttl that returns -1 (no expiration set)
+    #
+    # @return [Integer] Always returns -1 for the base implementation
+    #
+    def ttl
+      -1
+    end
+
+    # Base implementation of expires? that returns false
+    #
+    # @return [Boolean] Always returns false for the base implementation
+    #
+    def expires?
+      false
+    end
+
+    # Base implementation of expired? that returns false
+    #
+    # @param _threshold [Numeric] Ignored in base implementation
+    # @return [Boolean] Always returns false for the base implementation
+    #
+    def expired?(_threshold = 0)
+      false
+    end
+  end
+end

data/lib/familia/features/expiration.rb

@@ -1,13 +1,15 @@
 # lib/familia/features/expiration.rb
 
+require_relative 'expiration/extensions'
+
 module Familia
   module Features
     # Expiration is a feature that provides Time To Live (TTL) management for Familia
-    # objects and their associated Redis/Valkey data structures. It enables automatic
+    # objects and their associated Valkey/Redis data structures. It enables automatic
     # data cleanup and supports cascading expiration across related objects.
     #
     # This feature allows you to:
-    # - Set default expiration times at the class level
+    # - UnsortedSet default expiration times at the class level
     # - Update expiration times for individual objects
     # - Cascade expiration settings to related data structures
     # - Query remaining TTL for objects
@@ -33,7 +35,7 @@ module Familia
     #   session.update_expiration(30.minutes)
     #   session.ttl  # => 1799
     #
-    #   # Set custom expiration for new objects
+    #   # UnsortedSet custom expiration for new objects
     #   session.update_expiration(default_expiration: 2.hours)
     #
     # Class-Level Configuration:
@@ -141,33 +143,37 @@ module Familia
     #
     # Performance Considerations:
     #
-    # - TTL operations are performed on Redis/Valkey side with minimal overhead
+    # - TTL operations are performed on Valkey/Redis side with minimal overhead
     # - Cascading expiration uses pipelining for efficiency when possible
-    # - Zero expiration values skip Redis EXPIRE calls entirely
-    # - TTL queries are direct Redis operations (very fast)
+    # - Zero expiration values skip Valkey/Redis EXPIRE calls entirely
+    # - TTL queries are direct db operations (very fast)
     #
     module Expiration
       @default_expiration = nil
 
+      Familia::Base.add_feature self, :expiration
+
       using Familia::Refinements::TimeLiterals
 
       def self.included(base)
-        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-        base.extend ClassMethods
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
 
         # Initialize default_expiration instance variable if not already defined
         # This ensures the class has a place to store its default expiration setting
         return if base.instance_variable_defined?(:@default_expiration)
 
+        # The instance var here will return the value from the implementing
+        # model class (or nil if it's not set, as you'd expect).
         base.instance_variable_set(:@default_expiration, @default_expiration)
       end
 
-      # Familia::Expiration::ClassMethods
+      # Familia::Expiration::ModelClassMethods
       #
-      module ClassMethods
-        # Set the default expiration time for instances of this class
+      module ModelClassMethods
+        # UnsortedSet the default expiration time for instances of this class
         #
-        # @param expiration [Numeric] Time in seconds (can be fractional)
+        # @param value [Numeric] Time in seconds (can be fractional)
         #
         attr_writer :default_expiration
 
@@ -180,7 +186,7 @@ module Familia
         # @param num [Numeric, nil] Expiration time in seconds
         # @return [Float] The default expiration in seconds
         #
-        # @example Set default expiration
+        # @example UnsortedSet default expiration
         #   class MyModel < Familia::Horreum
         #     feature :expiration
         #     default_expiration 1.hour
@@ -195,7 +201,7 @@ module Familia
         end
       end
 
-      # Set the default expiration time for this instance
+      # UnsortedSet the default expiration time for this instance
       #
       # @param num [Numeric] Expiration time in seconds
       #
@@ -214,9 +220,9 @@ module Familia
         @default_expiration || self.class.default_expiration
       end
 
-      # Sets an expiration time for the Redis/Valkey data associated with this object
+      # Sets an expiration time for the Valkey/Redis data associated with this object
       #
-      # This method allows setting a Time To Live (TTL) for the data in Redis,
+      # This method allows setting a Time To Live (TTL) for the data in Valkey/Redis,
       # after which it will be automatically removed. The method also handles
       # cascading expiration to related data structures when applicable.
       #
@@ -262,15 +268,17 @@ module Familia
         # don't want to silently fail at setting expirations and cause data
         # retention issues (e.g. not removed in a timely fashion).
         unless default_expiration.is_a?(Numeric)
-          raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} given for #{self.class})"
+          raise Familia::Problem,
+                "Default expiration must be a number (#{default_expiration.class} given for #{self.class})"
         end
 
         unless default_expiration >= 0
-          raise Familia::Problem, "Default expiration must be non-negative (#{default_expiration} given for #{self.class})"
+          raise Familia::Problem,
+                "Default expiration must be non-negative (#{default_expiration} given for #{self.class})"
         end
 
         # If zero, simply skip setting an expiry for this key. If we were to set
-        # 0, Redis would drop the key immediately.
+        # 0, Valkey/Redis would drop the key immediately.
         if default_expiration.zero?
           Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
           return true
@@ -278,8 +286,9 @@ module Familia
 
         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, it's a boolean.
+        # The Valkey/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,
+        # it's a boolean.
         expire(default_expiration)
       end
 
@@ -295,7 +304,7 @@ module Familia
       #   expired_session.ttl  # => -1
       #
       def ttl
-        redis.ttl(dbkey)
+        dbclient.ttl(dbkey)
       end
 
       # Check if this object's data will expire
@@ -303,7 +312,7 @@ module Familia
       # @return [Boolean] true if TTL is set, false if data persists indefinitely
       #
       def expires?
-        ttl > 0
+        ttl.positive?
       end
 
       # Check if this object's data has expired or will expire soon
@@ -321,6 +330,7 @@ module Familia
         current_ttl = ttl
         return false if current_ttl == -1 # no expiration set
         return true  if current_ttl == -2 # key does not exist
+
         current_ttl <= threshold
       end
 
@@ -337,7 +347,7 @@ module Familia
       #
       def extend_expiration(duration)
         current_ttl = ttl
-        return false if current_ttl < 0  # No current expiration set
+        return false unless current_ttl.positive? # no current expiration set
 
         new_ttl = current_ttl + duration.to_f
         expire(new_ttl)
@@ -351,70 +361,8 @@ module Familia
       #   session.persist!
       #
       def persist!
-        redis.persist(dbkey)
+        dbclient.persist(dbkey)
       end
-
-      Familia::Base.add_feature self, :expiration
-    end
-  end
-end
-
-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.
-    #
-    # This is a no-op implementation that gets overridden by the :expiration
-    # feature. It accepts an optional default_expiration parameter to maintain
-    # interface compatibility with the overriding implementations.
-    #
-    # @param default_expiration [Numeric, nil] Time To Live in seconds
-    # @return [nil] Always returns nil for the base implementation
-    #
-    # @note This is a no-op implementation. Classes that need expiration
-    #       functionality should include the :expiration feature.
-    #
-    # @example Enable expiration feature
-    #   class MyModel < Familia::Horreum
-    #     feature :expiration
-    #     default_expiration 1.hour
-    #   end
-    #
-    def update_expiration(default_expiration: nil)
-      Familia.ld <<~LOG
-        [update_expiration] Expiration feature not enabled for #{self.class}.
-        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
-      LOG
-      nil
-    end
-
-    # Base implementation of ttl that returns -1 (no expiration set)
-    #
-    # @return [Integer] Always returns -1 for the base implementation
-    #
-    def ttl
-      -1
-    end
-
-    # Base implementation of expires? that returns false
-    #
-    # @return [Boolean] Always returns false for the base implementation
-    #
-    def expires?
-      false
-    end
-
-    # Base implementation of expired? that returns false
-    #
-    # @param threshold [Numeric] Ignored in base implementation
-    # @return [Boolean] Always returns false for the base implementation
-    #
-    def expired?(_threshold = 0)
-      false
     end
   end
 end

data/lib/familia/features/external_identifier.rb

@@ -5,9 +5,11 @@ module Familia
     # Familia::Features::ExternalIdentifier
     #
     module ExternalIdentifier
+      Familia::Base.add_feature self, :external_identifier, depends_on: [:object_identifier]
+
       def self.included(base)
-        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-        base.extend ClassMethods
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
 
         # Ensure default prefix is set in feature options
         base.add_feature_options(:external_identifier, prefix: 'ext')
@@ -41,11 +43,9 @@ module Familia
       #     feature :external_identifier
       #     field :email
       #   end
-      #
       #   user = User.new(email: 'user@example.com')
       #   user.objid  # => "01234567-89ab-7def-8000-123456789abc"
       #   user.extid  # => "ext_abc123def456ghi789" (deterministic from objid)
-      #
       #   # Same objid always produces same extid
       #   user2 = User.new(objid: user.objid, email: 'user@example.com')
       #   user2.extid  # => "ext_abc123def456ghi789" (identical to user.extid)
@@ -75,7 +75,7 @@ module Familia
 
               instance_variable_set(:"@#{field_name}", derived_extid)
 
-              # Update mapping if we have an identifier
+              # Update mapping if we have an identifier (objid)
               self.class.extid_lookup[derived_extid] = identifier if respond_to?(:identifier) && identifier
 
               derived_extid
@@ -86,7 +86,7 @@ module Familia
         # Override setter to preserve values during initialization
         #
         # This ensures that values passed during object initialization
-        # (e.g., when loading from Redis) are preserved and not overwritten
+        # (e.g., when loading from Valkey/Redis) are preserved and not overwritten
         # by the lazy generation logic.
         #
         # @param klass [Class] The class to define the method on
@@ -129,9 +129,9 @@ module Familia
         end
       end
 
-      # ExternalIdentifier::ClassMethods
+      # ExternalIdentifier::ModelClassMethods
       #
-      module ClassMethods
+      module ModelClassMethods
         # Find an object by its external identifier
         #
         # @param extid [String] The external identifier to search for
@@ -142,7 +142,7 @@ module Familia
 
           if Familia.debug?
             reference = caller(1..1).first
-            Familia.trace :FIND_BY_EXTID, Familia.dbclient, extid, reference
+            Familia.trace :FIND_BY_EXTID, nil, extid, reference
           end
 
           # Look up the primary ID from the external ID mapping
@@ -153,7 +153,8 @@ module Familia
           find_by_id(primary_id)
         rescue Familia::NotFound
           # If the object was deleted but mapping wasn't cleaned up
-          extid_lookup.remove_field(extid)
+          # we could autoclean here, as long as we log it.
+          # extid_lookup.remove_field(extid)
           nil
         end
       end
@@ -303,8 +304,6 @@ module Familia
           normalized
         end
       end
-
-      Familia::Base.add_feature self, :external_identifier, depends_on: [:object_identifier]
     end
   end
 end