familia 2.0.0.pre5 → 2.0.0.pre7

data/lib/familia/data_type.rb

@@ -27,12 +27,14 @@ module Familia
       attr_writer :logical_database, :uri
     end
 
+    # DataType::ClassMethods
+    #
     module ClassMethods
       # To be called inside every class that inherits DataType
       # +methname+ is the term used for the class and instance methods
       # that are created for the given +klass+ (e.g. set, list, etc)
       def register(klass, methname)
-        Familia.ld "[#{self}] Registering #{klass} as #{methname.inspect}"
+        Familia.trace :REGISTER, nil, "[#{self}] Registering #{klass} as #{methname.inspect}", caller(1..1) if Familia.debug?
 
         @registered_types[methname] = klass
       end
@@ -57,16 +59,16 @@ module Familia
       end
 
       def valid_keys_only(opts)
-        opts.select { |k, _| DataType.valid_options.include? k }
+        opts.slice(*DataType.valid_options)
       end
 
-      def has_relations?
-        @has_relations ||= false
+      def relations?
+        @has_relations ||= false # rubocop:disable ThreadSafety/ClassInstanceVariable
       end
     end
     extend ClassMethods
 
-    attr_reader :keystring, :parent, :opts
+    attr_reader :keystring, :opts
     attr_writer :dump_method, :load_method
 
     # +keystring+: If parent is set, this will be used as the suffix
@@ -115,7 +117,7 @@ module Familia
         # this point. This would result in a Familia::Problem being raised. So
         # to be on the safe-side here until we have a better understanding of
         # the issue, we'll just log the class name for each key-value pair.
-        Familia.ld " [setting] #{k} #{v.class}"
+        Familia.trace :SETTING, nil, " [setting] #{k} #{v.class}", caller(1..1) if Familia.debug?
         send(:"#{k}=", v) if respond_to? :"#{k}="
       end
 
@@ -199,6 +201,7 @@ module Familia
       @opts[:parent]
     end
 
+
     def logical_database
       @opts[:logical_database] || self.class.logical_database
     end

data/lib/familia/encryption/encrypted_data.rb

@@ -0,0 +1,137 @@
+# lib/familia/encryption/encrypted_data.rb
+
+module Familia
+  module Encryption
+    EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version) do
+      # Class methods for parsing and validation
+      def self.valid?(json_string)
+        return true if json_string.nil?  # Allow nil values
+        return false unless json_string.kind_of?(::String)
+
+        begin
+          parsed = JSON.parse(json_string, symbolize_names: true)
+          return false unless parsed.is_a?(Hash)
+
+          # Check for required fields
+          required_fields = [:algorithm, :nonce, :ciphertext, :auth_tag, :key_version]
+          result = required_fields.all? { |field| parsed.key?(field) }
+          Familia.ld "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
+          result
+        rescue JSON::ParserError => e
+          Familia.ld "[valid?] JSON error: #{e.message}"
+          false
+        end
+      end
+
+      def self.validate!(json_string)
+        return nil if json_string.nil?
+
+        unless json_string.kind_of?(::String)
+          raise EncryptionError, "Expected JSON string, got #{json_string.class}"
+        end
+
+        begin
+          parsed = JSON.parse(json_string, symbolize_names: true)
+        rescue JSON::ParserError => e
+          raise EncryptionError, "Invalid JSON structure: #{e.message}"
+        end
+
+        unless parsed.is_a?(Hash)
+          raise EncryptionError, "Expected JSON object, got #{parsed.class}"
+        end
+
+        required_fields = [:algorithm, :nonce, :ciphertext, :auth_tag, :key_version]
+        missing_fields = required_fields.reject { |field| parsed.key?(field) }
+
+        unless missing_fields.empty?
+          raise EncryptionError, "Missing required fields: #{missing_fields.join(', ')}"
+        end
+
+        new(**parsed)
+      end
+
+      def self.from_json(json_string)
+        validate!(json_string)
+      end
+
+      # Instance methods for decryptability validation
+      def decryptable?
+        return false unless algorithm && nonce && ciphertext && auth_tag && key_version
+
+        # Ensure Registry is set up before checking algorithms
+        Registry.setup! if Registry.providers.empty?
+
+        # Check if algorithm is supported
+        return false unless Registry.providers.key?(algorithm)
+
+        # Validate Base64 encoding of binary fields
+        begin
+          Base64.strict_decode64(nonce)
+          Base64.strict_decode64(ciphertext)
+          Base64.strict_decode64(auth_tag)
+        rescue ArgumentError
+          return false
+        end
+
+        true
+      end
+
+      def validate_decryptable!
+        unless algorithm
+          raise EncryptionError, "Missing algorithm field"
+        end
+
+        # Ensure Registry is set up before checking algorithms
+        Registry.setup! if Registry.providers.empty?
+
+        unless Registry.providers.key?(algorithm)
+          raise EncryptionError, "Unsupported algorithm: #{algorithm}"
+        end
+
+        unless nonce && ciphertext && auth_tag && key_version
+          missing = []
+          missing << 'nonce' unless nonce
+          missing << 'ciphertext' unless ciphertext
+          missing << 'auth_tag' unless auth_tag
+          missing << 'key_version' unless key_version
+          raise EncryptionError, "Missing required fields: #{missing.join(', ')}"
+        end
+
+        # Get the provider for size validation
+        provider = Registry.providers[algorithm]
+
+        # Validate Base64 encoding and sizes
+        begin
+          decoded_nonce = Base64.strict_decode64(nonce)
+          if decoded_nonce.bytesize != provider.nonce_size
+            raise EncryptionError, "Invalid nonce size: expected #{provider.nonce_size}, got #{decoded_nonce.bytesize}"
+          end
+        rescue ArgumentError
+          raise EncryptionError, "Invalid Base64 encoding in nonce field"
+        end
+
+        begin
+          Base64.strict_decode64(ciphertext)  # ciphertext can be variable size
+        rescue ArgumentError
+          raise EncryptionError, "Invalid Base64 encoding in ciphertext field"
+        end
+
+        begin
+          decoded_auth_tag = Base64.strict_decode64(auth_tag)
+          if decoded_auth_tag.bytesize != provider.auth_tag_size
+            raise EncryptionError, "Invalid auth_tag size: expected #{provider.auth_tag_size}, got #{decoded_auth_tag.bytesize}"
+          end
+        rescue ArgumentError
+          raise EncryptionError, "Invalid Base64 encoding in auth_tag field"
+        end
+
+        # Validate that the key version exists
+        unless Familia.config.encryption_keys&.key?(key_version.to_sym)
+          raise EncryptionError, "No key for version: #{key_version}"
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/familia/encryption/manager.rb

@@ -33,23 +33,28 @@ module Familia
       def decrypt(encrypted_json, context:, additional_data: nil)
         return nil if encrypted_json.nil? || encrypted_json.empty?
 
+        # Increment counter immediately to track all decryption attempts, even failed ones
+        Familia::Encryption.derivation_count.increment
+
         begin
           data = Familia::Encryption::EncryptedData.new(**JSON.parse(encrypted_json, symbolize_names: true))
 
           # Validate algorithm support
           provider = Registry.get(data.algorithm)
-          key = derive_key(context, version: data.key_version, provider: provider)
+          key = derive_key_without_increment(context, version: data.key_version, provider: provider)
 
           # Safely decode and validate sizes
           nonce = decode_and_validate(data.nonce, provider.nonce_size, 'nonce')
-          ciphertext = Base64.strict_decode64(data.ciphertext)
+          ciphertext = decode_and_validate_ciphertext(data.ciphertext)
           auth_tag = decode_and_validate(data.auth_tag, provider.auth_tag_size, 'auth_tag')
 
           provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
         rescue EncryptionError
           raise
-        rescue StandardError
-          raise EncryptionError, 'Decryption failed'
+        rescue JSON::ParserError => e
+          raise EncryptionError, "Invalid JSON structure: #{e.message}"
+        rescue StandardError => e
+          raise EncryptionError, "Decryption failed: #{e.message}"
         end
       ensure
         Familia::Encryption.secure_wipe(key) if key
@@ -61,12 +66,24 @@ module Familia
         decoded = Base64.strict_decode64(encoded)
         raise EncryptionError, 'Invalid encrypted data' unless decoded.bytesize == expected_size
         decoded
+      rescue ArgumentError => e
+        raise EncryptionError, "Invalid Base64 encoding in #{component} field"
+      end
+
+      def decode_and_validate_ciphertext(encoded)
+        Base64.strict_decode64(encoded)
+      rescue ArgumentError => e
+        raise EncryptionError, "Invalid Base64 encoding in ciphertext field"
       end
 
       def derive_key(context, version: nil, provider: nil)
         # Increment counter to prove no caching is happening
         Familia::Encryption.derivation_count.increment
 
+        derive_key_without_increment(context, version: version, provider: provider)
+      end
+
+      def derive_key_without_increment(context, version: nil, provider: nil)
         # Use provided provider or fall back to instance provider
         provider ||= @provider
 

data/lib/familia/encryption/providers/aes_gcm_provider.rb

@@ -87,6 +87,26 @@ module Familia
           key&.clear
         end
 
+        def self.nonce_size
+          NONCE_SIZE
+        end
+
+        def self.auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def nonce_size
+          NONCE_SIZE
+        end
+
+        def auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def algorithm
+          ALGORITHM
+        end
+
         private
 
         def create_cipher(mode)

data/lib/familia/encryption/providers/xchacha20_poly1305_provider.rb

@@ -106,6 +106,26 @@ module Familia
           key&.clear
         end
 
+        def self.nonce_size
+          NONCE_SIZE
+        end
+
+        def self.auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def nonce_size
+          NONCE_SIZE
+        end
+
+        def auth_tag_size
+          AUTH_TAG_SIZE
+        end
+
+        def algorithm
+          ALGORITHM
+        end
+
         private
 
         def validate_key_length!(key)

data/lib/familia/encryption.rb

@@ -10,12 +10,12 @@ require_relative 'encryption/providers/xchacha20_poly1305_provider'
 require_relative 'encryption/providers/aes_gcm_provider'
 require_relative 'encryption/registry'
 require_relative 'encryption/manager'
+require_relative 'encryption/encrypted_data'
 
 module Familia
   class EncryptionError < StandardError; end
 
   module Encryption
-    EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version)
 
     # Smart facade with provider selection and field-specific encryption
     #

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,293 @@
+# 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.instance_of?(expected_record.class) &&
+      @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(*)
+    '[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(*)
+    { concealed: true }
+  end
+
+  # Prevent exposure in JSON serialization
+  def to_json(*)
+    '"[CONCEALED]"'
+  end
+
+  # Prevent exposure in Rails serialization (as_json -> to_json)
+  def as_json(*)
+    '[CONCEALED]'
+  end
+
+  # Finalizer to attempt memory cleanup
+  def self.finalizer_proc(encrypted_data)
+    proc do
+      # Best effort cleanup - Ruby doesn't guarantee memory security
+      # Only clear if not frozen to avoid FrozenError
+      encrypted_data.clear if encrypted_data.respond_to?(:clear) && !encrypted_data.frozen?
+    end
+  end
+
+  private
+
+  # Check if a string looks like encrypted JSON data
+  def encrypted_json?(data)
+    Familia::Encryption::EncryptedData.valid?(data)
+  end
+
+end