familia 2.0.0.pre4 → 2.0.0.pre6

data/lib/familia/encryption_request_cache.rb

@@ -0,0 +1,68 @@
+# lib/familia/encryption_request_cache.rb
+#
+# Request-scoped caching for encryption keys (if needed for performance)
+# This should ONLY be enabled if performance testing shows it's necessary
+#
+# Usage in Rack middleware:
+#   class ClearEncryptionCacheMiddleware
+#     def call(env)
+#       Familia::Encryption.clear_request_cache!
+#       @app.call(env)
+#     ensure
+#       Familia::Encryption.clear_request_cache!
+#     end
+#   end
+
+module Familia
+  module Encryption
+    class << self
+      # Enable request-scoped caching (opt-in for performance)
+      def with_request_cache
+        Thread.current[:familia_request_cache_enabled] = true
+        Thread.current[:familia_request_cache] = {}
+        yield
+      ensure
+        clear_request_cache!
+      end
+
+      # Clear all cached keys and disable caching
+      def clear_request_cache!
+        if (cache = Thread.current[:familia_request_cache])
+          cache.each_value { |key| secure_wipe(key) }
+          cache.clear
+        end
+        Thread.current[:familia_request_cache_enabled] = false
+        Thread.current[:familia_request_cache] = nil
+      end
+
+      private
+
+      # Modified derive_key that uses request cache when enabled
+      def derive_key_with_optional_cache(context, version: nil)
+        version ||= current_key_version
+        master_key = get_master_key(version)
+
+        # Only use cache if explicitly enabled for this request
+        if Thread.current[:familia_request_cache_enabled]
+          cache = Thread.current[:familia_request_cache] ||= {}
+          cache_key = "#{version}:#{context}"
+
+          # Return cached key if available (within same request only)
+          if (cached = cache[cache_key])
+            return cached.dup
+          end
+
+          # Derive and cache for this request only
+          derived = perform_key_derivation(master_key, context)
+          cache[cache_key] = derived.dup
+          derived
+        else
+          # Default: no caching for maximum security
+          perform_key_derivation(master_key, context)
+        end
+      ensure
+        secure_wipe(master_key) if master_key
+      end
+    end
+  end
+end

data/lib/familia/errors.rb

@@ -34,8 +34,8 @@ module Familia
   # Set Familia.connection_provider or use middleware to provide connections.
   class NoConnectionAvailable < Problem; end
 
-  # Raised when attempting to refresh an object whose key doesn't exist in Redis
-  class KeyNotFoundError < Problem
+  # Raised when attempting to refresh an object whose key doesn't exist in the database
+  class KeyNotFoundError < NonUniqueKey
     attr_reader :key
 
     def initialize(key)
@@ -44,7 +44,21 @@ module Familia
     end
 
     def message
-      "Key not found in Redis: #{key}"
+      "Key not found: #{key}"
+    end
+  end
+
+  # Raised when attempting to create an object that already exists in the database
+  class RecordExistsError < NonUniqueKey
+    attr_reader :key
+
+    def initialize(key)
+      @key = key
+      super
+    end
+
+    def message
+      "Key already exists: #{key}"
     end
   end
 end

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

@@ -0,0 +1,295 @@
+# lib/familia/features/encrypted_fields/concealed_string.rb
+
+# ConcealedString
+#
+# A secure wrapper for encrypted field values that prevents accidental
+# plaintext leakage through serialization, logging, or debugging.
+#
+# Unlike RedactedString (which wraps plaintext), ConcealedString wraps
+# encrypted data and provides controlled decryption through the .reveal API.
+#
+# Security Model:
+#   - Contains encrypted JSON data, never plaintext
+#   - Requires explicit .reveal { } for decryption and plaintext access
+#   - ALL serialization methods return '[CONCEALED]' to prevent leakage
+#   - Maintains encryption context for proper AAD handling
+#   - Thread-safe and supports concurrent access
+#
+# Key Security Features:
+#   1. Universal Serialization Safety - ALL to_* methods protected
+#   2. Debugging Safety - inspect, logging, console output shows [CONCEALED]
+#   3. Exception Safety - never leaks plaintext in error messages
+#   4. Future-proof - any new serialization method automatically safe
+#   5. Memory Clearing - best-effort encrypted data clearing
+#
+# Critical Design Principles:
+#   - Secure by default - no auto-decryption anywhere
+#   - Explicit decryption - .reveal required for plaintext access
+#   - Comprehensive protection - covers ALL serialization paths
+#   - Auditable access - easy to grep for .reveal usage
+#
+# Example Usage:
+#   user = User.new
+#   user.secret_data = "sensitive info"     # Encrypts and wraps
+#   user.secret_data                        # Returns ConcealedString
+#   user.secret_data.reveal { |plain| ... } # Explicit decryption
+#   user.to_h                               # Safe - contains [CONCEALED]
+#   user.to_json                            # Safe - contains [CONCEALED]
+#
+class ConcealedString
+  # Create a concealed string wrapper
+  #
+  # @param encrypted_data [String] The encrypted JSON data
+  # @param record [Familia::Horreum] The record instance for context
+  # @param field_type [EncryptedFieldType] The field type for decryption
+  #
+  def initialize(encrypted_data, record, field_type)
+    @encrypted_data = encrypted_data.freeze
+    @record = record
+    @field_type = field_type
+    @cleared = false
+
+    # Parse and validate the encrypted data structure
+    if @encrypted_data
+      begin
+        @encrypted_data_obj = Familia::Encryption::EncryptedData.from_json(@encrypted_data)
+        # Validate that the encrypted data is decryptable (algorithm supported, etc.)
+        @encrypted_data_obj.validate_decryptable!
+      rescue Familia::EncryptionError => e
+        raise Familia::EncryptionError, e.message
+      rescue StandardError => e
+        raise Familia::EncryptionError, "Invalid encrypted data: #{e.message}"
+      end
+    end
+
+    ObjectSpace.define_finalizer(self, self.class.finalizer_proc(@encrypted_data))
+  end
+
+  # Primary API: reveal the decrypted plaintext in a controlled block
+  #
+  # This is the ONLY way to access plaintext from encrypted fields.
+  # The plaintext is decrypted fresh each time using the current
+  # record state and AAD context.
+  #
+  # Security Warning: Avoid operations inside the block that create
+  # uncontrolled copies of the plaintext (dup, interpolation, etc.)
+  #
+  # @yield [String] The decrypted plaintext value
+  # @return [Object] The return value of the block
+  #
+  # Example:
+  #   user.api_token.reveal do |token|
+  #     HTTP.post('/api', headers: { 'X-Token' => token })
+  #   end
+  #
+  def reveal
+    raise ArgumentError, 'Block required for reveal' unless block_given?
+    raise SecurityError, 'Encrypted data already cleared' if cleared?
+    raise SecurityError, 'No encrypted data to reveal' if @encrypted_data.nil?
+
+    # Decrypt using current record context and AAD
+    plaintext = @field_type.decrypt_value(@record, @encrypted_data)
+    yield plaintext
+  end
+
+  # Validate that this ConcealedString belongs to the given record context
+  #
+  # This prevents cross-context attacks where encrypted data is moved between
+  # different records or field contexts. While moving ConcealedString objects
+  # manually is not a normal use case, this provides defense in depth.
+  #
+  # @param expected_record [Familia::Horreum] The record that should own this data
+  # @param expected_field_name [Symbol] The field name that should own this data
+  # @return [Boolean] true if contexts match, false otherwise
+  #
+  def belongs_to_context?(expected_record, expected_field_name)
+    return false if @record.nil? || @field_type.nil?
+
+    @record.class.name == expected_record.class.name &&
+      @record.identifier == expected_record.identifier &&
+      @field_type.instance_variable_get(:@name) == expected_field_name
+  end
+
+  # Clear the encrypted data from memory
+  #
+  # Safe to call multiple times. This provides best-effort memory
+  # clearing within Ruby's limitations.
+  #
+  def clear!
+    return if @cleared
+
+    @encrypted_data = nil
+    @record = nil
+    @field_type = nil
+    @cleared = true
+    freeze
+  end
+
+  # Check if the encrypted data has been cleared
+  #
+  # @return [Boolean] true if cleared, false otherwise
+  #
+  def cleared?
+    @cleared
+  end
+
+  def empty?
+    @encrypted_data.to_s.empty?
+  end
+
+  # Returns true when it's literally the same object, otherwise false.
+  # This prevents timing attacks where an attacker could potentially
+  # infer information about the secret value through comparison timing
+  def ==(other)
+    object_id.equal?(other.object_id) # same object
+  end
+  alias eql? ==
+
+  # Access the encrypted data for database storage
+  #
+  # This method is used internally by the field type system
+  # for persisting the encrypted data to the database.
+  #
+  # @return [String, nil] The encrypted JSON data
+  #
+  def encrypted_value
+    @encrypted_data
+  end
+
+  # Prevent accidental exposure through string conversion and serialization
+  #
+  # Ruby has two string conversion methods with different purposes:
+  # - to_s: explicit conversion (obj.to_s, string interpolation "#{obj}")
+  # - to_str: implicit coercion (File.read(obj), "prefix" + obj)
+  #
+  # We implement to_s for safe logging/debugging but deliberately omit to_str
+  # to prevent encrypted data from being used where strings are expected.
+  #
+  def to_s
+    '[CONCEALED]'
+  end
+
+
+  # String methods that should return safe concealed values
+  def upcase
+    '[CONCEALED]'
+  end
+
+  def downcase
+    '[CONCEALED]'
+  end
+
+  def length
+    11  # Fixed concealed length to match '[CONCEALED]' length
+  end
+
+  def size
+    length
+  end
+
+  def present?
+    true  # Always return true since encrypted data exists
+  end
+
+  def blank?
+    false  # Never blank if encrypted data exists
+  end
+
+  # String concatenation operations return concealed result
+  def +(other)
+    '[CONCEALED]'
+  end
+
+  def concat(other)
+    '[CONCEALED]'
+  end
+
+  # Handle coercion for concatenation like "string" + concealed
+  def coerce(other)
+    if other.is_a?(String)
+      ['[CONCEALED]', '[CONCEALED]']
+    else
+      [other, '[CONCEALED]']
+    end
+  end
+
+  # String pattern matching methods
+  def strip
+    '[CONCEALED]'
+  end
+
+  def gsub(*args)
+    '[CONCEALED]'
+  end
+
+  def include?(substring)
+    false  # Never reveal substring presence
+  end
+
+  # Enumerable methods for safety
+  def map
+    yield '[CONCEALED]' if block_given?
+    ['[CONCEALED]']
+  end
+
+  def each
+    yield '[CONCEALED]' if block_given?
+    self
+  end
+
+  # Safe representation for debugging and console output
+  def inspect
+    '[CONCEALED]'
+  end
+
+  # Hash/Array serialization safety
+  def to_h
+    '[CONCEALED]'
+  end
+
+  def to_a
+    ['[CONCEALED]']
+  end
+
+  # Consistent hash to prevent timing attacks
+  def hash
+    ConcealedString.hash
+  end
+
+  # Pattern matching safety (Ruby 3.0+)
+  def deconstruct
+    ['[CONCEALED]']
+  end
+
+  def deconstruct_keys(keys)
+    { concealed: true }
+  end
+
+  # Prevent exposure in JSON serialization
+  def to_json(*args)
+    '"[CONCEALED]"'
+  end
+
+  # Prevent exposure in Rails serialization (as_json -> to_json)
+  def as_json(*args)
+    '[CONCEALED]'
+  end
+
+  private
+
+  # Check if a string looks like encrypted JSON data
+  def encrypted_json?(data)
+    Familia::Encryption::EncryptedData.valid?(data)
+  end
+
+  # Finalizer to attempt memory cleanup
+  def self.finalizer_proc(encrypted_data)
+    proc do |id|
+      # Best effort cleanup - Ruby doesn't guarantee memory security
+      # Only clear if not frozen to avoid FrozenError
+      if encrypted_data&.respond_to?(:clear) && !encrypted_data.frozen?
+        encrypted_data.clear
+      end
+    end
+  end
+end

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

@@ -0,0 +1,221 @@
+# 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)
+      # 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
+
+    def define_setter(klass)
+      field_name = @name
+      method_name = @method_name
+      field_type = self
+
+      handle_method_conflict(klass, :"#{method_name}=") do
+        klass.define_method :"#{method_name}=" do |value|
+          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
+
+    def define_getter(klass)
+      field_name = @name
+      method_name = @method_name
+      field_type = self
+
+      handle_method_conflict(klass, method_name) do
+        klass.define_method method_name do
+          # 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
+
+    def define_fast_writer(klass)
+      # Encrypted fields override base fast writer for security
+      return unless @fast_method_name&.to_s&.end_with?('!')
+
+      field_name = @name
+      method_name = @method_name
+      fast_method_name = @fast_method_name
+      field_type = self
+
+      handle_method_conflict(klass, fast_method_name) do
+        klass.define_method fast_method_name do |val|
+          raise ArgumentError, "#{fast_method_name} requires a value" if val.nil?
+
+          # Set via the setter method to get proper ConcealedString wrapping
+          send(:"#{method_name}=", val) if method_name
+
+          # 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
+    end
+
+    # Encrypt a value for the given record
+    def encrypt_value(record, value)
+      context = build_context(record)
+      additional_data = build_aad(record)
+
+      Familia::Encryption.encrypt(value, context: context, additional_data: additional_data)
+    end
+
+    # Decrypt a value for the given record
+    def decrypt_value(record, encrypted)
+      context = build_context(record)
+      additional_data = build_aad(record)
+
+      Familia::Encryption.decrypt(encrypted, context: context, additional_data: additional_data)
+    end
+
+    def persistent?
+      true
+    end
+
+    def category
+      :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
+    def build_context(record)
+      "#{record.class.name}:#{@name}:#{record.identifier}"
+    end
+
+    # Build Additional Authenticated Data (AAD) for authenticated encryption
+    #
+    # AAD provides cryptographic binding between encrypted field values and their
+    # containing record context. This prevents attackers from moving encrypted
+    # values between different records or field contexts, even with database access.
+    #
+    # ## Consistent AAD Behavior
+    #
+    # 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.
+    #
+    # **All Records (both new and persisted):**
+    # - AAD = record.identifier (no aad_fields) or SHA256(identifier:field1:field2:...)
+    # - Consistent cryptographic binding to record identity
+    # - Moving encrypted values between records/contexts will fail decryption
+    #
+    # ## Security Implications
+    #
+    # This design prevents several attack vectors:
+    #
+    # 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**: 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.
+    #
+    # ## Usage Patterns
+    #
+    # ```ruby
+    # # No AAD fields - basic record binding
+    # encrypted_field :secret_value
+    #
+    # # With AAD fields - multi-field binding
+    # encrypted_field :content, aad_fields: [:owner_id, :doc_type]
+    # ```
+    #
+    # @param record [Familia::Horreum] The record instance containing this field
+    # @return [String, nil] AAD string for encryption, or nil if no identifier
+    #
+    def build_aad(record)
+      # 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, use class:field:identifier
+        base_components.join(':')
+      else
+        # 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
+end

data/lib/familia/features/encrypted_fields.rb

@@ -0,0 +1,28 @@
+# lib/familia/features/encrypted_fields.rb
+
+require_relative 'encrypted_fields/encrypted_field_type'
+
+module Familia
+  module Features
+    module EncryptedFields
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Define an encrypted field
+        # @param name [Symbol] Field name
+        # @param aad_fields [Array<Symbol>] Optional fields to include in AAD
+        # @param kwargs [Hash] Additional field options
+        def encrypted_field(name, aad_fields: [], **)
+          require_relative 'encrypted_fields/encrypted_field_type'
+
+          field_type = EncryptedFieldType.new(name, aad_fields: aad_fields, **)
+          register_field_type(field_type)
+        end
+      end
+
+      Familia::Base.add_feature self, :encrypted_fields
+    end
+  end
+end