familia 2.0.0.pre5 → 2.0.0.pre7

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

@@ -1,13 +1,15 @@
 # lib/familia/field_types/encrypted_field_type.rb
 
 require_relative '../../field_type'
+require_relative 'concealed_string'
 
 module Familia
   class EncryptedFieldType < FieldType
     attr_reader :aad_fields
 
     def initialize(name, aad_fields: [], **options)
-      super(name, **options.merge(on_conflict: :raise))
+      # Encrypted fields are not loggable by default for security
+      super(name, **options.merge(on_conflict: :raise, loggable: false))
       @aad_fields = Array(aad_fields).freeze
     end
 
@@ -18,8 +20,24 @@ module Familia
 
       handle_method_conflict(klass, :"#{method_name}=") do
         klass.define_method :"#{method_name}=" do |value|
-          encrypted = value.nil? ? nil : field_type.encrypt_value(self, value)
-          instance_variable_set(:"@#{field_name}", encrypted)
+          if value.nil?
+            instance_variable_set(:"@#{field_name}", nil)
+          elsif value.is_a?(::String) && value.empty?
+            # Handle empty strings - treat as nil for encrypted fields
+            instance_variable_set(:"@#{field_name}", nil)
+          elsif value.is_a?(ConcealedString)
+            # Already concealed, store as-is
+            instance_variable_set(:"@#{field_name}", value)
+          elsif field_type.encrypted_json?(value)
+            # Already encrypted JSON from database - wrap in ConcealedString without re-encrypting
+            concealed = ConcealedString.new(value, self, field_type)
+            instance_variable_set(:"@#{field_name}", concealed)
+          else
+            # Encrypt plaintext and wrap in ConcealedString
+            encrypted = field_type.encrypt_value(self, value)
+            concealed = ConcealedString.new(encrypted, self, field_type)
+            instance_variable_set(:"@#{field_name}", concealed)
+          end
         end
       end
     end
@@ -31,8 +49,36 @@ module Familia
 
       handle_method_conflict(klass, method_name) do
         klass.define_method method_name do
-          encrypted = instance_variable_get(:"@#{field_name}")
-          encrypted.nil? ? nil : field_type.decrypt_value(self, encrypted)
+          # Return ConcealedString directly - no auto-decryption!
+          # Caller must use .reveal { } for plaintext access
+          concealed = instance_variable_get(:"@#{field_name}")
+
+          # Return nil directly if that's what was set
+          return nil if concealed.nil?
+
+          # 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)
+            # 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
+            begin
+              concealed = ConcealedString.new(concealed, self, field_type)
+              instance_variable_set(:"@#{field_name}", concealed)
+            rescue Familia::EncryptionError => e
+              # Increment derivation counter for failed validation attempts (similar to decrypt failures)
+              Familia::Encryption.derivation_count.increment
+              raise e
+            end
+          end
+
+          # 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}"
+          end
+
+          concealed
         end
       end
     end
@@ -50,10 +96,16 @@ module Familia
         klass.define_method fast_method_name do |val|
           raise ArgumentError, "#{fast_method_name} requires a value" if val.nil?
 
-          encrypted = field_type.encrypt_value(self, val)
+          # Set via the setter method to get proper ConcealedString wrapping
           send(:"#{method_name}=", val) if method_name
 
-          ret = hset(field_name, encrypted)
+          # Get the ConcealedString and extract encrypted data for storage
+          concealed = instance_variable_get(:"@#{field_name}")
+          encrypted_data = concealed&.encrypted_value
+
+          return false if encrypted_data.nil?
+
+          ret = hset(field_name, encrypted_data)
           ret.zero? || ret.positive?
         end
       end
@@ -83,6 +135,11 @@ module Familia
       :encrypted
     end
 
+    # Check if a string looks like encrypted JSON data
+    def encrypted_json?(data)
+      Familia::Encryption::EncryptedData.valid?(data)
+    end
+
     private
 
     # Build encryption context string
@@ -96,19 +153,15 @@ module Familia
     # containing record context. This prevents attackers from moving encrypted
     # values between different records or field contexts, even with database access.
     #
-    # ## Persistence-Dependent Behavior
+    # ## Consistent AAD Behavior
     #
-    # AAD is only generated for records that exist in the database (`record.exists?`).
-    # This creates an important behavioral distinction:
+    # AAD is now consistently generated based on the record's identifier, regardless
+    # of persistence state. This ensures that encrypted values remain decryptable
+    # after save/load cycles while still providing security benefits.
     #
-    # **Before Save (record.exists? == false):**
-    # - AAD = nil
-    # - Encryption context = "ClassName:fieldname:identifier" only
-    # - Values can be encrypted/decrypted freely in memory
-    #
-    # **After Save (record.exists? == true):**
+    # **All Records (both new and persisted):**
     # - AAD = record.identifier (no aad_fields) or SHA256(identifier:field1:field2:...)
-    # - Full cryptographic binding to database state
+    # - Consistent cryptographic binding to record identity
     # - Moving encrypted values between records/contexts will fail decryption
     #
     # ## Security Implications
@@ -118,8 +171,8 @@ module Familia
     # 1. **Field Value Swapping**: With aad_fields specified, encrypted values
     #    become bound to other field values. Changing owner_id breaks decryption.
     #
-    # 2. **Cross-Record Migration**: Even without aad_fields, encrypted values
-    #    are bound to their specific record identifier after persistence.
+    # 2. **Cross-Record Migration**: Encrypted values are bound to their specific
+    #    record identifier, preventing cross-record value movement.
     #
     # 3. **Temporal Consistency**: Re-encrypting the same plaintext after
     #    field changes produces different ciphertext due to AAD changes.
@@ -135,18 +188,33 @@ module Familia
     # ```
     #
     # @param record [Familia::Horreum] The record instance containing this field
-    # @return [String, nil] AAD string for encryption, or nil for unsaved records
+    # @return [String, nil] AAD string for encryption, or nil if no identifier
     #
     def build_aad(record)
-      return nil unless record.exists?
+      # AAD provides consistent context-aware binding, regardless of persistence state
+      # This ensures save/load cycles work while maintaining context isolation
+      identifier = record.identifier
+      return nil if identifier.nil? || identifier.to_s.empty?
+
+      # Include class and field name in AAD for context isolation
+      # This prevents cross-class and cross-field value migration
+      base_components = [record.class.name, @name, identifier]
 
       if @aad_fields.empty?
-        # When no AAD fields specified, just use identifier
-        record.identifier
+        # When no AAD fields specified, use class:field:identifier
+        base_components.join(':')
       else
-        # Include specified field values in AAD
-        values = @aad_fields.map { |field| record.send(field) }
-        Digest::SHA256.hexdigest([record.identifier, *values].compact.join(':'))
+        # 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
       end
     end
   end

data/lib/familia/features/encrypted_fields.rb

@@ -4,22 +4,431 @@ 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
+    # with field-specific key derivation to protect data at rest while maintaining
+    # easy access patterns for authorized applications.
+    #
+    # This feature automatically encrypts field values before storage and decrypts
+    # them on access, providing seamless integration with existing code while
+    # ensuring sensitive data is never stored in plaintext.
+    #
+    # Supported Encryption Algorithms:
+    # - XChaCha20-Poly1305 (preferred, requires rbnacl gem)
+    # - AES-256-GCM (fallback, uses OpenSSL)
+    #
+    # Example:
+    #
+    #   class Vault < Familia::Horreum
+    #     feature :encrypted_fields
+    #
+    #     field :name                    # Regular unencrypted field
+    #     encrypted_field :secret_key    # Encrypted storage
+    #     encrypted_field :api_token     # Another encrypted field
+    #     encrypted_field :love_letter   # Ultra-sensitive field
+    #   end
+    #
+    #   vault = Vault.new(
+    #     name: "Production Vault",
+    #     secret_key: "super-secret-key-123",
+    #     api_token: "sk-1234567890abcdef",
+    #     love_letter: "Dear Alice, I love you. -Bob"
+    #   )
+    #
+    #   vault.save
+    #   # Only 'name' is stored in plaintext
+    #   # secret_key, api_token, love_letter are encrypted
+    #
+    #   # Access is transparent
+    #   vault.secret_key    # => "super-secret-key-123" (decrypted automatically)
+    #   vault.api_token     # => "sk-1234567890abcdef" (decrypted automatically)
+    #
+    # Security Features:
+    #
+    # Each encrypted field uses a unique encryption key derived from:
+    # - Master encryption key (from Familia.encryption_key)
+    # - Field name (cryptographic domain separation)
+    # - Record identifier (per-record key derivation)
+    # - Class name (per-class key derivation)
+    #
+    # This ensures that:
+    # - Swapping encrypted values between fields fails to decrypt
+    # - Each record has unique encryption keys
+    # - Different classes cannot decrypt each other's data
+    # - Field-level access control is cryptographically enforced
+    #
+    # Cryptographic Design:
+    #
+    #   # XChaCha20-Poly1305 (preferred)
+    #   - 256-bit keys (32 bytes)
+    #   - 192-bit nonces (24 bytes) - extended nonce space
+    #   - 128-bit authentication tags (16 bytes)
+    #   - BLAKE2b key derivation with personalization
+    #
+    #   # AES-256-GCM (fallback)
+    #   - 256-bit keys (32 bytes)
+    #   - 96-bit nonces (12 bytes) - standard GCM nonce
+    #   - 128-bit authentication tags (16 bytes)
+    #   - HKDF-SHA256 key derivation
+    #
+    # Ciphertext Format:
+    #
+    # Encrypted data is stored as JSON with algorithm-specific metadata:
+    #
+    #   {
+    #     "algorithm": "xchacha20poly1305",
+    #     "nonce": "base64_encoded_nonce",
+    #     "ciphertext": "base64_encoded_data",
+    #     "auth_tag": "base64_encoded_tag",
+    #     "key_version": "v1"
+    #   }
+    #
+    # Additional Authenticated Data (AAD):
+    #
+    # For extra security, you can include other field values in the authentication:
+    #
+    #   class SecureDocument < Familia::Horreum
+    #     feature :encrypted_fields
+    #
+    #     field :doc_id, :owner_id, :classification
+    #     encrypted_field :content, aad_fields: [:doc_id, :owner_id, :classification]
+    #   end
+    #
+    #   # The content can only be decrypted if doc_id, owner_id, and classification
+    #   # values match those used during encryption
+    #
+    # Passphrase Protection:
+    #
+    # For ultra-sensitive fields, require user passphrases for decryption:
+    #
+    #   class PersonalVault < Familia::Horreum
+    #     feature :encrypted_fields
+    #
+    #     field :user_id
+    #     encrypted_field :diary_entry    # Ultra-sensitive
+    #     encrypted_field :photos         # Ultra-sensitive
+    #   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)
+    #
+    # Memory Safety:
+    #
+    # Encrypted fields return ConcealedString objects that provide memory protection:
+    #
+    #   secret = vault.secret_key
+    #   secret.class               # => ConcealedString
+    #   puts secret                # => "[CONCEALED]" (automatic redaction)
+    #   secret.inspect             # => "[CONCEALED]" (automatic redaction)
+    #
+    #   # Safe access pattern
+    #   secret.expose do |value|
+    #     # Use value directly without creating copies
+    #     api_call(authorization: "Bearer #{value}")
+    #   end
+    #
+    #   # Direct access (use carefully)
+    #   raw_value = secret.value   # Returns actual decrypted string
+    #
+    #   # Explicit cleanup
+    #   secret.clear!              # Best-effort memory wiping
+    #
+    # Error Handling:
+    #
+    # The feature provides specific error types for different failure modes:
+    #
+    #   # 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 key
+    #   Familia.encryption_key = nil
+    #   vault.secret_key  # => Familia::EncryptionError: No encryption key configured
+    #
+    # Configuration:
+    #
+    #   # Set master encryption key (required)
+    #   Familia.configure do |config|
+    #     config.encryption_key = ENV['FAMILIA_ENCRYPTION_KEY']
+    #     config.encryption_personalization = 'MyApp-2024'  # Optional customization
+    #   end
+    #
+    #   # Generate a new encryption key
+    #   key = Familia::Encryption.generate_key
+    #   puts key  # => "base64-encoded-32-byte-key"
+    #
+    # Key Rotation:
+    #
+    # The feature supports key versioning for seamless key rotation:
+    #
+    #   # Step 1: Add new key while keeping old key
+    #   Familia.configure do |config|
+    #     config.encryption_key = new_key
+    #     config.legacy_encryption_keys = { 'v1' => old_key }
+    #   end
+    #
+    #   # Step 2: Objects decrypt with old key, encrypt with new key
+    #   vault.secret_key = "new-secret"  # Encrypted with new key
+    #   vault.save
+    #
+    #   # Step 3: After all data is re-encrypted, remove legacy key
+    #
+    # Integration Patterns:
+    #
+    #   # Rails application
+    #   class User < ApplicationRecord
+    #     include Familia::Horreum
+    #     feature :encrypted_fields
+    #
+    #     field :user_id
+    #     encrypted_field :credit_card_number
+    #     encrypted_field :ssn, aad_fields: [:user_id]
+    #   end
+    #
+    #   # API serialization (encrypted fields excluded by default)
+    #   class UserSerializer
+    #     def self.serialize(user)
+    #       {
+    #         id: user.user_id,
+    #         created_at: user.created_at,
+    #         # credit_card_number and ssn are NOT included
+    #       }
+    #     end
+    #   end
+    #
+    #   # Background job processing
+    #   class PaymentProcessor
+    #     def process_payment(user_id)
+    #       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
+    #
+    #       # Clear sensitive data from memory
+    #       user.credit_card_number.clear!
+    #     end
+    #   end
+    #
+    # Performance Considerations:
+    #
+    # - Encryption/decryption adds ~1-5ms overhead per field
+    # - Key derivation is cached per field/record combination
+    # - XChaCha20-Poly1305 is ~2x faster than AES-256-GCM
+    # - Memory allocation increases due to ciphertext expansion
+    # - Consider batching operations for high-throughput scenarios
+    #
+    # Security Limitations:
+    #
+    # ⚠️ Important: Ruby provides NO memory safety guarantees:
+    # - No secure memory wiping (best-effort only)
+    # - Garbage collector may copy secrets
+    # - String operations create uncontrolled copies
+    # - Memory dumps may contain plaintext secrets
+    #
+    # For highly sensitive applications, consider:
+    # - External key management (HashiCorp Vault, AWS KMS)
+    # - Hardware Security Modules (HSMs)
+    # - Languages with secure memory handling
+    # - Dedicated cryptographic appliances
+    #
+    # Threat Model:
+    #
+    # ✅ Protected Against:
+    # - Database compromise (encrypted data only)
+    # - Field value swapping (field-specific keys)
+    # - Cross-record attacks (record-specific keys)
+    # - Tampering (authenticated encryption)
+    #
+    # ❌ Not Protected Against:
+    # - Master key compromise (all data compromised)
+    # - Application memory compromise (plaintext in RAM)
+    # - Side-channel attacks (timing, power analysis)
+    # - Insider threats with application access
+    #
     module EncryptedFields
       def self.included(base)
+        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
+
+        # Initialize encrypted fields tracking
+        base.instance_variable_set(:@encrypted_fields, []) unless base.instance_variable_defined?(:@encrypted_fields)
       end
 
       module ClassMethods
-        # Define an encrypted field
+        # Define an encrypted field that transparently encrypts/decrypts values
+        #
+        # Encrypted fields are stored as JSON objects containing the encrypted
+        # ciphertext along with cryptographic metadata. Values are automatically
+        # encrypted on assignment and decrypted on access.
+        #
         # @param name [Symbol] Field name
-        # @param aad_fields [Array<Symbol>] Optional fields to include in AAD
+        # @param aad_fields [Array<Symbol>] Additional fields to include in authentication
         # @param kwargs [Hash] Additional field options
-        def encrypted_field(name, aad_fields: [], **)
+        #
+        # @example Basic encrypted field
+        #   class Vault < Familia::Horreum
+        #     feature :encrypted_fields
+        #     encrypted_field :secret_key
+        #   end
+        #
+        # @example Encrypted field with additional authentication
+        #   class Document < Familia::Horreum
+        #     feature :encrypted_fields
+        #     field :doc_id, :owner_id
+        #     encrypted_field :content, aad_fields: [:doc_id, :owner_id]
+        #   end
+        #
+        def encrypted_field(name, aad_fields: [], **kwargs)
+          @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, **)
+          field_type = EncryptedFieldType.new(name, aad_fields: aad_fields, **kwargs)
           register_field_type(field_type)
         end
+
+        # Returns list of encrypted field names defined on this class
+        #
+        # @return [Array<Symbol>] Array of encrypted field names
+        #
+        def encrypted_fields
+          @encrypted_fields || []
+        end
+
+        # Check if a field is encrypted
+        #
+        # @param field_name [Symbol] The field name to check
+        # @return [Boolean] true if field is encrypted, false otherwise
+        #
+        def encrypted_field?(field_name)
+          encrypted_fields.include?(field_name.to_sym)
+        end
+
+        # Get encryption algorithm information
+        #
+        # @return [Hash] Hash containing encryption algorithm details
+        #
+        def encryption_info
+          provider = Familia::Encryption.current_provider
+          {
+            algorithm: provider.algorithm_name,
+            key_size: provider.key_size,
+            nonce_size: provider.nonce_size,
+            tag_size: provider.tag_size
+          }
+        end
+      end
+
+      # Check if this instance has any encrypted fields with values
+      #
+      # @return [Boolean] true if any encrypted fields have values
+      #
+      # TODO: Missing test coverage
+      def encrypted_data?
+        self.class.encrypted_fields.any? do |field_name|
+          field_value = instance_variable_get("@#{field_name}")
+          !field_value.nil?
+        end
+      end
+
+      # Clear all encrypted field values from memory
+      #
+      # This method iterates through all encrypted fields and calls clear!
+      # on any ConcealedString instances. Use this for cleanup when the
+      # object is no longer needed.
+      #
+      # @return [void]
+      #
+      # @example Clear all secrets when done
+      #   vault = Vault.new(secret_key: 'secret', api_token: 'token123')
+      #   # ... use vault ...
+      #   vault.clear_encrypted_fields!
+      #
+      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
+        end
+      end
+
+      # Check if all encrypted fields have been cleared from memory
+      #
+      # @return [Boolean] true if all encrypted fields are cleared, false otherwise
+      #
+      def encrypted_fields_cleared?
+        self.class.encrypted_fields.all? do |field_name|
+          field_value = instance_variable_get("@#{field_name}")
+          field_value.nil? || (field_value.respond_to?(:cleared?) && field_value.cleared?)
+        end
+      end
+
+      # Re-encrypt all encrypted fields with current encryption settings
+      #
+      # This method is useful for key rotation or algorithm upgrades.
+      # It decrypts all encrypted fields and re-encrypts them with the
+      # current encryption configuration.
+      #
+      # @return [Boolean] true if re-encryption succeeded
+      #
+      # @example Re-encrypt after key rotation
+      #   vault.re_encrypt_fields!
+      #   vault.save
+      #
+      def re_encrypt_fields!
+        self.class.encrypted_fields.each do |field_name|
+          current_value = send(field_name)
+          next if current_value.nil?
+
+          # Force re-encryption by setting the value again
+          if current_value.respond_to?(:value)
+            send("#{field_name}=", current_value.value)
+          else
+            send("#{field_name}=", current_value)
+          end
+        end
+        true
+      end
+
+      # Get encryption status for all encrypted fields
+      #
+      # Returns a hash showing the encryption status of each encrypted field,
+      # useful for debugging and monitoring.
+      #
+      # @return [Hash] Hash with field names as keys and status information
+      #
+      # @example Check encryption status
+      #   vault.encrypted_fields_status
+      #   # => {
+      #   #   secret_key: { encrypted: true, algorithm: "xchacha20poly1305", cleared: false },
+      #   #   api_token: { encrypted: true, algorithm: "aes-256-gcm", cleared: true }
+      #   # }
+      #
+      def encrypted_fields_status
+        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
+        end
       end
 
       Familia::Base.add_feature self, :encrypted_fields