familia 2.0.0.pre5 → 2.0.0.pre6

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

@@ -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/expiration.rb

@@ -8,7 +8,7 @@ module Familia
       @default_expiration = nil
 
       def self.included(base)
-        Familia.ld "[#{base}] Loaded #{self}"
+        Familia.trace :LOADED!, nil, self, caller(1..1) if Familia.debug?
         base.extend ClassMethods
 
         # Optionally define default_expiration in the class to make

data/lib/familia/features/quantization.rb

@@ -3,7 +3,7 @@
 module Familia::Features
   module Quantization
     def self.included(base)
-      Familia.ld "[#{base}] Loaded #{self}"
+      Familia.trace :included, base, self, caller(1..1) if Familia.debug?
       base.extend ClassMethods
     end
 

data/lib/familia/features/safe_dump.rb

@@ -54,7 +54,7 @@ module Familia::Features
     @safe_dump_field_map = {}
 
     def self.included(base)
-      Familia.ld "[#{self}] Enabled in #{base}"
+      Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
       base.extend ClassMethods
 
       # Optionally define safe_dump_fields in the class to make

data/lib/familia/features/transient_fields/redacted_string.rb

@@ -141,7 +141,7 @@ class RedactedString
   def inspect = to_s
   def cleared? = @cleared
 
-  # Returns true when it's literally the same object, otherwsie false.
+  # 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)

data/lib/familia/features/transient_fields.rb

@@ -12,7 +12,7 @@ module Familia
     #
     module TransientFields
       def self.included(base)
-        Familia.ld "[#{base}] Loaded #{self}"
+        Familia.trace :included, base, self, caller(1..1) if Familia.debug?
         base.extend ClassMethods
       end
 

data/lib/familia/field_type.rb

@@ -27,7 +27,7 @@ module Familia
   #   end
   #
   class FieldType
-    attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict
+    attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
 
     # Initialize a new field type
     #
@@ -38,9 +38,11 @@ module Familia
     #   (defaults to "#{name}!"). If false, no fast method is created
     # @param on_conflict [Symbol] Conflict resolution strategy when method
     #   already exists (:raise, :skip, :warn, :overwrite)
+    # @param loggable [Boolean] Whether this field should be included in
+    #   serialization and logging operations (default: true)
     # @param options [Hash] Additional options for the field type
     #
-    def initialize(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, **options)
+    def initialize(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, loggable: true, **options)
       @name = name.to_sym
       @method_name = as == false ? nil : as.to_sym
       @fast_method_name = fast_method == false ? nil : fast_method&.to_sym
@@ -51,6 +53,7 @@ module Familia
       end
 
       @on_conflict = on_conflict
+      @loggable = loggable
       @options = options
     end
 

data/lib/familia/horreum/{connection.rb → core/connection.rb}

@@ -2,8 +2,8 @@
 
 module Familia
   class Horreum
-    # Familia::Horreum::Connection
-    #
+    # Connection: Valkey connection management for Horreum instances
+    # Provides both instance and class-level connection methods
     module Connection
       attr_reader :uri
 
@@ -69,11 +69,5 @@ module Familia
         block_result
       end
     end
-
-    # include for instance methods after it's loaded. Note that Horreum::Utils
-    # are also included and at one time also has a uri method. This connection
-    # module is also extended for the class level methods. It will require some
-    # disambiguation at some point.
-    include Familia::Horreum::Connection
   end
 end

data/lib/familia/horreum/{database_commands.rb → core/database_commands.rb}

@@ -37,7 +37,7 @@ module Familia
       # @note The default behavior maintains backward compatibility by treating empty hashes
       #   as non-existent. Use `check_size: false` for pure key existence checking.
       def exists?(check_size: true)
-        key_exists = self.class.dbclient.exists?(dbkey)
+        key_exists = self.class.exists?(identifier)
         return key_exists unless check_size
 
         key_exists && !size.zero?
@@ -106,6 +106,19 @@ module Familia
         dbclient.hset dbkey, field, value
       end
 
+      # Sets field in the hash stored at key to value, only if field does not yet exist.
+      # If key does not exist, a new key holding a hash is created. If field already exists,
+      # this operation has no effect.
+      #
+      # @param field [String] The field to set in the hash
+      # @param value [String] The value to set for the field
+      # @return [Integer] 1 if the field is a new field in the hash and the value was set,
+      #   0 if the field already exists in the hash and no operation was performed
+      def hsetnx(field, value)
+        Familia.trace :HSETNX, dbclient, field, caller(1..1) if Familia.debug?
+        dbclient.hsetnx dbkey, field, value
+      end
+
       def hmset(hsh = {})
         hsh ||= to_h
         Familia.trace :HMSET, dbclient, hsh, caller(1..1) if Familia.debug?
@@ -165,7 +178,5 @@ module Familia
       end
       alias clear delete!
     end
-
-    include DatabaseCommands # these become Familia::Horreum instance methods
   end
 end