familia 2.0.0.pre3 → 2.0.0.pre5

data/lib/familia/{datatype → data_type}/types/unsorted_set.rb

@@ -1,8 +1,7 @@
-# lib/familia/datatype/types/unsorted_set.rb
+# lib/familia/data_type/types/unsorted_set.rb
 
 module Familia
   class Set < DataType
-
     # Returns the number of elements in the unsorted set
     # @return [Integer] number of elements
     def element_count
@@ -36,36 +35,36 @@ module Familia
       dbclient.smembers(dbkey)
     end
 
-    def each(&blk)
-      members.each(&blk)
+    def each(&)
+      members.each(&)
     end
 
-    def each_with_index(&blk)
-      members.each_with_index(&blk)
+    def each_with_index(&)
+      members.each_with_index(&)
     end
 
-    def collect(&blk)
-      members.collect(&blk)
+    def collect(&)
+      members.collect(&)
     end
 
-    def select(&blk)
-      members.select(&blk)
+    def select(&)
+      members.select(&)
     end
 
-    def eachraw(&blk)
-      membersraw.each(&blk)
+    def eachraw(&)
+      membersraw.each(&)
     end
 
-    def eachraw_with_index(&blk)
-      membersraw.each_with_index(&blk)
+    def eachraw_with_index(&)
+      membersraw.each_with_index(&)
     end
 
-    def collectraw(&blk)
-      membersraw.collect(&blk)
+    def collectraw(&)
+      membersraw.collect(&)
     end
 
-    def selectraw(&blk)
-      membersraw.select(&blk)
+    def selectraw(&)
+      membersraw.select(&)
     end
 
     def member?(val)

data/lib/familia/{datatype.rb → data_type.rb}

@@ -1,10 +1,9 @@
-# lib/familia/datatype.rb
+# lib/familia/data_type.rb
 
-require_relative 'datatype/commands'
-require_relative 'datatype/serialization'
+require_relative 'data_type/commands'
+require_relative 'data_type/serialization'
 
 module Familia
-
   # DataType - Base class for Database data type wrappers
   #
   # This class provides common functionality for various Database data types
@@ -54,7 +53,7 @@ module Familia
         obj.default_expiration = default_expiration # method added via Features::Expiration
         obj.uri = uri
         obj.parent = self
-        super(obj)
+        super
       end
 
       def valid_keys_only(opts)
@@ -102,7 +101,6 @@ module Familia
     # Connection precendence: uses the database connection of the parent or the
     # value of opts[:dbclient] or Familia.dbclient (in that order).
     def initialize(keystring, opts = {})
-      #Familia.ld " [initializing] #{self.class} #{opts}"
       @keystring = keystring
       @keystring = @keystring.join(Familia.delim) if @keystring.is_a?(Array)
 
@@ -172,7 +170,7 @@ module Familia
         parent.dbkey(keystring)
       elsif parent_class?
         # This is a class-level datatype object so the parent class' dbkey
-        # method is defined in Familia::Horreum::ClassMethods.
+        # method is defined in Familia::Horreum::DefinitionMethods.
         parent.dbkey(keystring, nil)
       else
         # This is a standalone DataType object where it's keystring
@@ -235,9 +233,9 @@ module Familia
     include Serialization
   end
 
-  require_relative 'datatype/types/list'
-  require_relative 'datatype/types/unsorted_set'
-  require_relative 'datatype/types/sorted_set'
-  require_relative 'datatype/types/hashkey'
-  require_relative 'datatype/types/string'
+  require_relative 'data_type/types/list'
+  require_relative 'data_type/types/unsorted_set'
+  require_relative 'data_type/types/sorted_set'
+  require_relative 'data_type/types/hashkey'
+  require_relative 'data_type/types/string'
 end

data/lib/familia/encryption/manager.rb

@@ -0,0 +1,102 @@
+# lib/familia/encryption/manager.rb
+
+module Familia
+  module Encryption
+    # High-level encryption manager - replaces monolithic Encryption module
+    class Manager
+      attr_reader :provider
+
+      def initialize(algorithm: nil)
+        Registry.setup! if Registry.providers.empty?
+        @provider = algorithm ? Registry.get(algorithm) : Registry.default_provider
+        raise EncryptionError, 'No encryption provider available' unless @provider
+      end
+
+      def encrypt(plaintext, context:, additional_data: nil)
+        return nil if plaintext.to_s.empty?
+
+        key = derive_key(context)
+
+        result = @provider.encrypt(plaintext, key, additional_data)
+
+        Familia::Encryption::EncryptedData.new(
+          algorithm: @provider.algorithm,
+          nonce: Base64.strict_encode64(result[:nonce]),
+          ciphertext: Base64.strict_encode64(result[:ciphertext]),
+          auth_tag: Base64.strict_encode64(result[:auth_tag]),
+          key_version: current_key_version
+        ).to_h.to_json
+      ensure
+        Familia::Encryption.secure_wipe(key) if key
+      end
+
+      def decrypt(encrypted_json, context:, additional_data: nil)
+        return nil if encrypted_json.nil? || encrypted_json.empty?
+
+        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)
+
+          # Safely decode and validate sizes
+          nonce = decode_and_validate(data.nonce, provider.nonce_size, 'nonce')
+          ciphertext = Base64.strict_decode64(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'
+        end
+      ensure
+        Familia::Encryption.secure_wipe(key) if key
+      end
+
+      private
+
+      def decode_and_validate(encoded, expected_size, component)
+        decoded = Base64.strict_decode64(encoded)
+        raise EncryptionError, 'Invalid encrypted data' unless decoded.bytesize == expected_size
+        decoded
+      end
+
+      def derive_key(context, version: nil, provider: nil)
+        # Increment counter to prove no caching is happening
+        Familia::Encryption.derivation_count.increment
+
+        # Use provided provider or fall back to instance provider
+        provider ||= @provider
+
+        # Require explicit provider in decrypt context
+        raise EncryptionError, 'Provider required for key derivation' unless provider
+
+        version ||= current_key_version
+        master_key = get_master_key(version)
+
+        provider.derive_key(master_key, context)
+      ensure
+        Familia::Encryption.secure_wipe(master_key) if master_key
+      end
+
+      def get_master_key(version)
+        raise EncryptionError, 'Key version cannot be nil' if version.nil?
+
+        key = encryption_keys[version] || encryption_keys[version.to_sym] || encryption_keys[version.to_s]
+        raise EncryptionError, "No key for version: #{version}" unless key
+
+        Base64.strict_decode64(key)
+      end
+
+      def encryption_keys
+        Familia.config.encryption_keys || {}
+      end
+
+      def current_key_version
+        Familia.config.current_key_version
+      end
+    end
+  end
+end

data/lib/familia/encryption/provider.rb

@@ -0,0 +1,49 @@
+# lib/familia/encryption/provider.rb
+
+module Familia
+  module Encryption
+    # Base provider class - similar to FieldType pattern
+    class Provider
+      attr_reader :algorithm, :nonce_size, :auth_tag_size
+
+      def initialize
+        @algorithm = self.class::ALGORITHM
+        @nonce_size = self.class::NONCE_SIZE
+        @auth_tag_size = self.class::AUTH_TAG_SIZE
+      end
+
+      # Public interface methods that subclasses must implement
+      def encrypt(plaintext, key, additional_data = nil)
+        raise NotImplementedError
+      end
+
+      def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+        raise NotImplementedError
+      end
+
+      def generate_nonce
+        raise NotImplementedError
+      end
+
+      def derive_key(master_key, context)
+        raise NotImplementedError
+      end
+
+      # Clear key from memory (best effort, no security guarantees)
+      # Ruby provides no reliable way to securely wipe memory
+      def secure_wipe(key)
+        key&.clear if key.respond_to?(:clear)
+      end
+
+      # Check if this provider is available
+      def self.available?
+        raise NotImplementedError
+      end
+
+      # Priority for automatic selection (higher = preferred)
+      def self.priority
+        0
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# lib/familia/encryption/providers/aes_gcm_provider.rb
+
+# ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
+#
+# This encryption provider, like all Ruby-based cryptographic implementations,
+# stores secrets (keys, plaintext, derived keys) as Ruby strings in memory.
+#
+# SECURITY IMPLICATIONS:
+# - Keys remain in memory after use (garbage collection timing is unpredictable)
+# - Ruby strings cannot be securely wiped from memory
+# - Memory dumps may contain cryptographic secrets
+# - Swap files may persist secrets to disk
+# - String operations create copies that persist in memory
+#
+# Ruby provides NO memory safety guarantees for cryptographic secrets.
+#
+# For production systems handling sensitive data, consider:
+# - Hardware Security Modules (HSMs)
+# - External key management services
+# - Languages with manual memory management
+# - Cryptographic appliances with secure memory
+
+module Familia
+  module Encryption
+    module Providers
+      class AESGCMProvider < Provider
+        ALGORITHM = 'aes-256-gcm'.freeze
+        NONCE_SIZE = 12
+        AUTH_TAG_SIZE = 16
+
+        def self.available?
+          true # OpenSSL is always available
+        end
+
+        def self.priority
+          50 # Fallback option
+        end
+
+        def encrypt(plaintext, key, additional_data = nil)
+          validate_key_length!(key)
+          nonce = generate_nonce
+          cipher = create_cipher(:encrypt)
+          cipher.key = key
+          cipher.iv = nonce
+          cipher.auth_data = additional_data.to_s if additional_data
+
+          ciphertext = cipher.update(plaintext.to_s) + cipher.final
+
+          {
+            ciphertext: ciphertext,
+            auth_tag: cipher.auth_tag,
+            nonce: nonce
+          }
+        end
+
+        def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+          validate_key_length!(key)
+          cipher = create_cipher(:decrypt)
+          cipher.key = key
+          cipher.iv = nonce
+          cipher.auth_tag = auth_tag
+          cipher.auth_data = additional_data.to_s if additional_data
+
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError
+          raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
+        end
+
+        def generate_nonce
+          OpenSSL::Random.random_bytes(NONCE_SIZE)
+        end
+
+        def derive_key(master_key, context, personal: nil)
+          validate_key_length!(master_key)
+          info = personal ? "#{context}:#{personal}" : context
+          OpenSSL::KDF.hkdf(
+            master_key,
+            salt: 'FamiliaEncryption',
+            info: info,
+            length: 32,
+            hash: 'SHA256'
+          )
+        end
+
+        # Clear key from memory (no security guarantees in Ruby)
+        def secure_wipe(key)
+          key&.clear
+        end
+
+        private
+
+        def create_cipher(mode)
+          OpenSSL::Cipher.new('aes-256-gcm').tap { |c| c.public_send(mode) }
+        end
+
+        def validate_key_length!(key)
+          raise EncryptionError, 'Key cannot be nil' if key.nil?
+          raise EncryptionError, 'Key must be at least 32 bytes' if key.bytesize < 32
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,184 @@
+# lib/familia/encryption/providers/secure_xchacha20_poly1305_provider.rb
+
+# ⚠️  PROTOTYPE IMPLEMENTATION - NOT FOR PRODUCTION USE ⚠️
+#
+# This provider is a PROTOTYPE demonstrating alternate memory security practices
+# for handling secrets in Ruby. It is NOT intended for use with actual sensitive
+# data or production systems.
+#
+# LIMITATIONS:
+# - Still relies on Ruby strings internally (unavoidable language constraint)
+# - RbNaCl library stores keys as strings regardless of our efforts
+# - Ruby's garbage collector behavior cannot be fully controlled
+# - No guarantee of complete memory cleanup
+#
+# This implementation serves as:
+# - Educational example of security-conscious programming
+# - Research prototype for future FFI-based implementations
+# - Demonstration of defense-in-depth techniques
+#
+# For actual cryptographic applications, consider:
+# - Hardware Security Modules (HSMs)
+# - Dedicated cryptographic appliances
+# - Languages with manual memory management (C, Rust)
+# - External key management services
+
+begin
+  require 'rbnacl'
+  require 'ffi'
+rescue LoadError
+  # Dependencies not available - provider will report as unavailable
+end
+
+module Familia
+  module Encryption
+    module Providers
+      # Enhanced XChaCha20Poly1305Provider with improved memory security
+      #
+      # While complete avoidance of Ruby strings for secrets is challenging due to
+      # RbNaCl's internal implementation, this provider implements several security
+      # improvements:
+      #
+      # 1. Minimizes key lifetime in memory
+      # 2. Uses immediate secure wiping after operations
+      # 3. Avoids unnecessary key duplication
+      # 4. Uses locked memory where possible (future enhancement)
+      #
+      class SecureXChaCha20Poly1305Provider < Provider
+        ALGORITHM = 'xchacha20poly1305-secure'.freeze
+        NONCE_SIZE = 24
+        AUTH_TAG_SIZE = 16
+
+        def self.available?
+          !!defined?(RbNaCl) && !!defined?(FFI)
+        end
+
+        def self.priority
+          110 # Higher than regular XChaCha20Poly1305Provider
+        end
+
+        def encrypt(plaintext, key, additional_data = nil)
+          validate_key_length!(key)
+
+          # Generate nonce first to avoid holding onto key longer than necessary
+          nonce = generate_nonce
+
+          # Minimize key exposure by performing operation immediately
+          result = perform_encryption(plaintext, key, nonce, additional_data)
+
+          # Attempt to clear the key parameter (if mutable)
+          secure_wipe(key)
+
+          result
+        end
+
+        def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+          validate_key_length!(key)
+
+          # Minimize key exposure by performing operation immediately
+          begin
+            result = perform_decryption(ciphertext, key, nonce, auth_tag, additional_data)
+          ensure
+            # Attempt to clear the key parameter (if mutable)
+            secure_wipe(key)
+          end
+
+          result
+        end
+
+        def generate_nonce
+          RbNaCl::Random.random_bytes(NONCE_SIZE)
+        end
+
+        # Enhanced key derivation with immediate cleanup
+        def derive_key(master_key, context, personal: nil)
+          validate_key_length!(master_key)
+
+          raw_personal = personal || Familia.config.encryption_personalization
+          if raw_personal.include?("\0")
+            raise EncryptionError, 'Personalization string must not contain null bytes'
+          end
+
+          personal_string = raw_personal.ljust(16, "\0")
+
+          # Perform derivation and immediately clear intermediate values
+          derived_key = RbNaCl::Hash.blake2b(
+            context.force_encoding('BINARY'),
+            key: master_key,
+            digest_size: 32,
+            personal: personal_string
+          )
+
+          # Clear personalization string from memory
+          personal_string.clear
+
+          # Return derived key (caller responsible for secure cleanup)
+          derived_key
+        end
+
+        # Clear key from memory (still no security guarantees in Ruby)
+        def secure_wipe(key)
+          key&.clear
+        end
+
+        private
+
+        def perform_encryption(plaintext, key, nonce, additional_data)
+          # Create AEAD instance (this internally copies the key)
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          aad = additional_data.to_s
+          ciphertext_with_tag = box.encrypt(nonce, plaintext.to_s, aad)
+
+          result = {
+            ciphertext: ciphertext_with_tag[0...-16],
+            auth_tag: ciphertext_with_tag[-16..-1],
+            nonce: nonce
+          }
+
+          # Clear intermediate values
+          ciphertext_with_tag.clear
+
+          result
+        ensure
+          # Clear the AEAD instance's internal key if possible
+          clear_aead_instance(box) if box
+        end
+
+        def perform_decryption(ciphertext, key, nonce, auth_tag, additional_data)
+          # Create AEAD instance (this internally copies the key)
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          ciphertext_with_tag = ciphertext + auth_tag
+          aad = additional_data.to_s
+
+          result = box.decrypt(nonce, ciphertext_with_tag, aad)
+
+          # Clear intermediate values
+          ciphertext_with_tag.clear
+
+          result
+        rescue RbNaCl::CryptoError
+          raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
+        ensure
+          # Clear the AEAD instance's internal key if possible
+          clear_aead_instance(box) if box
+        end
+
+        def clear_aead_instance(aead_instance)
+          # Attempt to clear RbNaCl's internal key storage
+          # This is a best-effort cleanup since RbNaCl stores keys as strings internally
+          if aead_instance.instance_variable_defined?(:@key)
+            internal_key = aead_instance.instance_variable_get(:@key)
+            secure_wipe(internal_key) if internal_key
+          end
+        end
+
+        def validate_key_length!(key)
+          raise EncryptionError, 'Key cannot be nil' if key.nil?
+          raise EncryptionError, 'Key must be at least 32 bytes' if key.bytesize < 32
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# lib/familia/encryption/providers/xchacha20_poly1305_provider.rb
+
+# ⚠️  RUBY MEMORY SAFETY WARNING ⚠️
+#
+# This encryption provider, like all Ruby-based cryptographic implementations,
+# stores secrets (keys, plaintext, derived keys) as Ruby strings in memory.
+#
+# SECURITY IMPLICATIONS:
+# - Keys remain in memory after use (garbage collection timing is unpredictable)
+# - Ruby strings cannot be securely wiped from memory
+# - Memory dumps may contain cryptographic secrets
+# - Swap files may persist secrets to disk
+# - String operations create copies that persist in memory
+#
+# Ruby provides NO memory safety guarantees for cryptographic secrets.
+#
+# For production systems handling sensitive data, consider:
+# - Hardware Security Modules (HSMs)
+# - External key management services
+# - Languages with manual memory management
+# - Cryptographic appliances with secure memory
+
+begin
+  require 'rbnacl'
+rescue LoadError
+  # RbNaCl not available - provider will report as unavailable
+  # To add: gem 'rbnacl', '~> 7.1', '>= 7.1.1'
+end
+
+module Familia
+  module Encryption
+    module Providers
+      class XChaCha20Poly1305Provider < Provider
+        ALGORITHM = 'xchacha20poly1305'.freeze
+        NONCE_SIZE = 24
+        AUTH_TAG_SIZE = 16
+
+        def self.available?
+          !!defined?(RbNaCl)
+        end
+
+        def self.priority
+          100 # Highest priority - best in class
+        end
+
+        def encrypt(plaintext, key, additional_data = nil)
+          validate_key_length!(key)
+          nonce = generate_nonce
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          aad = additional_data.to_s
+          ciphertext_with_tag = box.encrypt(nonce, plaintext.to_s, aad)
+
+          {
+            ciphertext: ciphertext_with_tag[0...-16],
+            auth_tag: ciphertext_with_tag[-16..-1],
+            nonce: nonce
+          }
+        end
+
+        def decrypt(ciphertext, key, nonce, auth_tag, additional_data = nil)
+          validate_key_length!(key)
+          box = RbNaCl::AEAD::XChaCha20Poly1305IETF.new(key)
+
+          ciphertext_with_tag = ciphertext + auth_tag
+          aad = additional_data.to_s
+
+          box.decrypt(nonce, ciphertext_with_tag, aad)
+        rescue RbNaCl::CryptoError
+          raise EncryptionError, 'Decryption failed - invalid key or corrupted data'
+        end
+
+        def generate_nonce
+          RbNaCl::Random.random_bytes(NONCE_SIZE)
+        end
+
+        # Derives a context-specific encryption key using BLAKE2b.
+        #
+        # The personalization parameter provides cryptographic domain separation,
+        # ensuring that derived keys are unique per application even when using
+        # identical master keys and contexts. This prevents key reuse across
+        # different applications or library versions.
+        #
+        # @param master_key [String] The master key (must be >= 32 bytes)
+        # @param context [String] Context string for key derivation
+        # @param personal [String, nil] Optional personalization override
+        # @return [String] 32-byte derived key
+        def derive_key(master_key, context, personal: nil)
+          validate_key_length!(master_key)
+          raw_personal = personal || Familia.config.encryption_personalization
+          if raw_personal.include?("\0")
+            raise EncryptionError, 'Personalization string must not contain null bytes'
+          end
+          personal_string = raw_personal.ljust(16, "\0")
+
+          RbNaCl::Hash.blake2b(
+            context.force_encoding('BINARY'),
+            key: master_key,
+            digest_size: 32,
+            personal: personal_string
+          )
+        end
+
+        # Clear key from memory (no security guarantees in Ruby)
+        def secure_wipe(key)
+          key&.clear
+        end
+
+        private
+
+        def validate_key_length!(key)
+          raise EncryptionError, 'Key cannot be nil' if key.nil?
+          raise EncryptionError, 'Key must be at least 32 bytes' if key.bytesize < 32
+        end
+      end
+    end
+  end
+end