familia 2.0.0.pre15 → 2.0.0.pre17

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: After all data is re-encrypted, remove legacy key
+    #   # Step 3: Re-encrypt existing records
+    #   vault.re_encrypt_fields!  # Uses current key version
+    #   vault.save
+    #
+    #   # 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,17 +259,17 @@ module Familia
     # - Insider threats with application access
     #
     module EncryptedFields
-      Familia::Base.add_feature self, :encrypted_fields
+      Familia::Base.add_feature self, :encrypted_fields, depends_on: nil, field_group: :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
@@ -289,13 +293,16 @@ 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'
+          # Add to field_groups if the group exists
+          if field_groups&.key?(:encrypted_fields)
+            field_groups[:encrypted_fields] << name
+          end
 
-          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
 
@@ -326,7 +333,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
@@ -359,9 +366,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
 
@@ -421,15 +426,15 @@ 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
     end

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

@@ -51,7 +51,7 @@ module Familia
 
     # Base implementation of expired? that returns false
     #
-    # @param threshold [Numeric] Ignored in base implementation
+    # @param _threshold [Numeric] Ignored in base implementation
     # @return [Boolean] Always returns false for the base implementation
     #
     def expired?(_threshold = 0)

data/lib/familia/features/expiration.rb

@@ -5,11 +5,11 @@ 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
@@ -35,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:
@@ -143,10 +143,10 @@ 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
@@ -156,22 +156,24 @@ module Familia
       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
 
@@ -184,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
@@ -199,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
       #
@@ -218,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.
       #
@@ -266,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
@@ -282,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
 
@@ -299,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
@@ -307,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
@@ -325,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
 
@@ -341,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)
@@ -355,9 +361,8 @@ module Familia
       #   session.persist!
       #
       def persist!
-        redis.persist(dbkey)
+        dbclient.persist(dbkey)
       end
-
     end
   end
 end

data/lib/familia/features/external_identifier.rb

@@ -5,12 +5,12 @@ 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
+        base.include ModelInstanceMethods
 
         # Ensure default prefix is set in feature options
         base.add_feature_options(:external_identifier, prefix: 'ext')
@@ -44,11 +44,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)
@@ -78,9 +76,6 @@ module Familia
 
               instance_variable_set(:"@#{field_name}", derived_extid)
 
-              # Update mapping if we have an identifier
-              self.class.extid_lookup[derived_extid] = identifier if respond_to?(:identifier) && identifier
-
               derived_extid
             end
           end
@@ -89,7 +84,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
@@ -106,11 +101,6 @@ module Familia
 
               # Set the new value
               instance_variable_set(:"@#{field_name}", value)
-
-              # Update mapping if we have both extid and identifier
-              return unless value && respond_to?(:identifier) && identifier
-
-              self.class.extid_lookup[value] = identifier
             end
           end
         end
@@ -132,9 +122,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
@@ -145,7 +135,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
@@ -156,11 +146,60 @@ 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
 
+      # Instance methods for external identifier management
+      module ModelInstanceMethods
+        # Override save to update extid_lookup mapping
+        #
+        # This ensures the extid_lookup index is populated during save operations
+        # rather than during object initialization, preventing unwanted database
+        # writes when calling .new()
+        #
+        # @param update_expiration [Boolean] Whether to update key expiration
+        # @return [Boolean] True if save was successful
+        #
+        def save(update_expiration: true)
+          result = super
+
+          # Update extid_lookup mapping after successful save
+          if result && respond_to?(:extid) && respond_to?(:identifier)
+            current_extid = extid  # Triggers lazy generation if needed
+            if current_extid && identifier
+              self.class.extid_lookup[current_extid] = identifier
+            end
+          end
+
+          result
+        end
+
+        # Override save_if_not_exists to update extid_lookup mapping
+        #
+        # This ensures the extid_lookup index is populated during create operations
+        # which use save_if_not_exists instead of save.
+        #
+        # @param update_expiration [Boolean] Whether to update key expiration
+        # @return [Boolean] True if save was successful
+        #
+        def save_if_not_exists(update_expiration: true)
+          result = super
+
+          # Update extid_lookup mapping after successful save
+          if result && respond_to?(:extid) && respond_to?(:identifier)
+            current_extid = extid  # Triggers lazy generation if needed
+            if current_extid && identifier
+              self.class.extid_lookup[current_extid] = identifier
+            end
+          end
+
+          result
+        end
+      end
+
       # Derives a deterministic, public-facing external identifier from the object's
       # internal `objid`.
       #
@@ -306,7 +345,6 @@ module Familia
           normalized
         end
       end
-
     end
   end
 end