familia 2.0.0.pre3 → 2.0.0.pre5

data/docs/wiki/Home.md

@@ -0,0 +1,49 @@
+# Familia Encrypted Fields Documentation
+
+Welcome to the Familia encrypted fields feature documentation. This Wiki provides comprehensive guides for implementing field-level encryption in your Familia-based applications.
+
+## 📚 Documentation Structure
+
+### Essential Reading (Start Here)
+
+1. **[Encrypted Fields Overview](Encrypted-Fields-Overview.md)** - Quick introduction and basic usage
+
+2. **[Implementation Guide](Implementation-Guide.md)** - Configuration details and advanced usage
+
+3. **[API Reference](API-Reference.md)** - Class and method documentation
+
+### Deep Dives
+
+4. **[Security Model](Security-Model.md)** - Cryptographic design and Protected vs unprotected scenarios
+
+### Operations (As Needed)
+
+5. **[Migration Guide](Migration-Guide.md)** - Upgrading existing fields _(coming soon)_
+6. **[Key Management](Key-Management.md)** - Rotation and best practices _(coming soon)_
+
+## 🚀 Quick Start
+
+```ruby
+# 1. Add encrypted field to your model
+class User < Familia::Horreum
+  encrypted_field :secret_recipe
+end
+
+# 2. Configure encryption key
+Familia.configure do |config|
+  config.encryption_keys = { v1: ENV['FAMILIA_ENCRYPTION_KEY'] }
+  config.current_key_version = :v1
+end
+
+# 3. Use like any other field
+user = User.new(secret_recipe: "donna's cookies")
+user.save
+user.secret_recipe  # => "donna's cookies" (automatically decrypted)
+```
+
+
+## Related Resources
+
+- [Familia README](https://github.com/delano/familia) - Main project documentation
+- [Issue #57](https://github.com/delano/familia/issues/57) - Original feature proposal
+- [Issue #58](https://github.com/delano/familia/issues/58) - Wiki documentation tracking

data/docs/wiki/Implementation-Guide.md

@@ -0,0 +1,183 @@
+# Implementation Guide
+
+## Architecture Overview
+
+The encrypted fields feature extends Familia's existing field system with transformation hooks:
+
+```
+User Input → Field Setter → Serialize Transform → Encryption → Redis
+Redis → Decryption → Deserialize Transform → Field Getter → User Output
+```
+
+## Core Components
+
+### 1. Transform Hooks
+
+Fields now support transform callbacks:
+
+```ruby
+FieldDefinition = Data.define(
+  :field_name,
+  :method_name,
+  :serialize_transform,    # Called before storage
+  :deserialize_transform   # Called after retrieval
+)
+```
+
+### 2. Encryption Module
+
+Handles the cryptographic operations:
+
+```ruby
+module Familia::Encryption
+  # Encrypts with field-specific derived key
+  def self.encrypt(plaintext, context:, additional_data: nil)
+
+  # Decrypts and verifies authenticity
+  def self.decrypt(ciphertext, context:, additional_data: nil)
+end
+```
+
+### 3. Key Derivation
+
+Each field gets a unique encryption key:
+
+```
+Master Key + Field Context → HKDF/BLAKE2b → Field-Specific Key
+```
+
+## Implementation Steps
+
+### Step 1: Enable Encryption
+
+```ruby
+class MyModel < Familia::Horreum
+  # Add the feature (optional if globally enabled)
+  feature :encryption
+
+  # Define encrypted fields
+  encrypted_field :sensitive_data
+  encrypted_field :api_key
+end
+```
+
+### Step 2: Configure Keys
+
+```ruby
+# config/initializers/familia.rb
+Familia.configure do |config|
+  config.encryption_keys = {
+    v1: ENV['FAMILIA_ENCRYPTION_KEY_V1']
+  }
+  config.current_key_version = :v1
+end
+
+# Validate configuration at startup
+Familia::Encryption.validate_configuration!
+```
+
+### Step 3: Generate Keys
+
+```bash
+# Generate a secure key
+$ familia encryption:generate_key --bits 256
+# => base64_encoded_key_here
+
+# Add to environment
+$ echo "FAMILIA_ENCRYPTION_KEY_V1=base64_encoded_key_here" >> .env
+```
+
+## Advanced Usage
+
+### Custom Field Names
+
+```ruby
+encrypted_field :favorite_snack, as: :top_secret_snack_preference
+```
+
+### Passphrase Protection
+
+```ruby
+class Vault < Familia::Horreum
+  encrypted_field :secret
+
+  def unlock(passphrase)
+    # Passphrase becomes part of encryption context
+    self.secret(passphrase_value: passphrase)
+  end
+end
+```
+
+### Batch Operations
+
+```ruby
+# Efficient bulk encryption
+customers = Customer.batch_create([
+  { email: 'user1@example.com', favorite_snack: 'chocolate chip cookies' },
+  { email: 'user2@example.com', favorite_snack: 'leftover pizza' }
+])
+```
+
+## Performance Optimization
+
+### Request-Scoped Key Caching
+
+```ruby
+# Automatically enabled in web frameworks
+# Manual control for other contexts:
+Familia::Encryption.with_key_cache do
+  # All operations here share derived keys
+  Customer.find_each { |c| c.process }
+end
+```
+
+### Memory Management
+
+With libsodium installed:
+- Keys are automatically wiped from memory
+- Plaintext values cleared after use
+
+## Testing
+
+```ruby
+# Test helper
+RSpec.configure do |config|
+  config.include Familia::EncryptionTestHelpers
+
+  config.around(:each, :encryption) do |example|
+    with_test_encryption_keys { example.run }
+  end
+end
+
+# In tests
+it "encrypts sensitive fields", :encryption do
+  user = User.create(favorite_snack: "leftover pizza")
+
+  # Verify encryption in Redis
+  raw_value = redis.hget(user.rediskey, "favorite_snack")
+  expect(raw_value).not_to include("leftover pizza")
+  expect(JSON.parse(raw_value)).to have_key("ciphertext")
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"No encryption key configured"**
+   - Ensure `FAMILIA_ENCRYPTION_KEY` is set
+   - Check `Familia.config.encryption_keys`
+
+2. **"Decryption failed"**
+   - Verify correct key version
+   - Check if data was encrypted with different key
+
+3. **Performance degradation**
+   - Enable key caching
+   - Consider installing libsodium gem
+
+## Next Steps
+
+- [Security Model](Security-Model) - Understand the cryptographic design
+- [Key Management](Key-Management) - Rotation and best practices
+- [Migration Guide](Migration-Guide) - Upgrade existing fields

data/docs/wiki/Security-Model.md

@@ -0,0 +1,143 @@
+# Security Model
+
+## Cryptographic Design
+
+### Encryption Algorithms
+
+**Primary (with libsodium):**
+- Algorithm: XChaCha20-Poly1305
+- Key Size: 256 bits
+- Nonce Size: 192 bits
+- Authentication Tag: 128 bits
+
+**Fallback (with OpenSSL):**
+- Algorithm: AES-256-GCM
+- Key Size: 256 bits
+- IV Size: 96 bits
+- Authentication Tag: 128 bits
+
+### Key Derivation
+
+Each field gets a unique key derived from the master key:
+
+```
+Field Key = KDF(Master Key, Context)
+
+Where Context = "ClassName:field_name:record_identifier"
+```
+
+**KDF Functions:**
+- Libsodium: BLAKE2b with personalization
+- OpenSSL: HKDF-SHA256
+
+### Ciphertext Format
+
+```json
+{
+  "library": "libsodium",
+  "algorithm": "xchacha20poly1305",
+  "nonce": "base64_encoded_nonce",
+  "ciphertext": "base64_encoded_ciphertext",
+  "key_version": "v1_2504"
+}
+```
+
+## Threat Model
+
+### Protected Against
+
+#### Database Compromise
+- All sensitive fields encrypted with strong keys
+- Attackers see only ciphertext
+
+#### Field Value Swapping
+- Field-specific key derivation prevents cross-field decryption
+- Swapped values fail to decrypt
+
+#### Replay Attacks
+- Each encryption uses unique random nonce
+- Old values remain valid but are distinct encryptions
+
+#### Tampering
+- Authenticated encryption (Poly1305/GCM)
+- Modified ciphertext fails authentication
+
+### Not Protected Against
+
+#### Application Memory Compromise
+- Plaintext values exist in Ruby memory
+- Mitigation: Use libsodium for memory wiping, minimize plaintext lifetime
+
+#### Master Key Compromise
+- All encrypted data compromised if keys obtained
+- Mitigation: Secure key storage, regular rotation, hardware security modules
+
+#### Side-Channel Attacks
+- Key recovery through timing/power analysis
+- Mitigation: Libsodium provides constant-time operations
+
+## Additional Security Features
+
+### Passphrase Protection
+
+For ultra-sensitive fields, add user passphrases:
+
+```ruby
+encrypted_field :love_letter
+
+# Passphrase required for decryption
+vault.love_letter(passphrase_value: user_passphrase)
+```
+
+**How it works:**
+1. Passphrase hashed with SHA-256
+2. Hash included in Additional Authenticated Data (AAD)
+3. Wrong passphrase = authentication failure
+4. Passphrase never stored, only verified
+
+### Memory Safety
+
+**With libsodium:**
+- Automatic zeroing of sensitive memory
+- Constant-time comparisons
+- Protected memory pages when available
+
+**Without libsodium:**
+- Warning logged about reduced security
+- Ruby GC may retain plaintext copies
+- Timing attacks theoretically possible
+
+### RedactedString
+
+Prevents accidental logging of sensitive data:
+
+```ruby
+class RedactedString < String
+  def to_s
+    '[REDACTED]'
+  end
+
+  def inspect
+    '[REDACTED]'
+  end
+end
+
+# In logs:
+logger.info "Love letter: #{user.love_letter}"  # => "Love letter: [REDACTED]"
+```
+
+## Security Checklist
+
+### Development
+
+- [ ] Never log plaintext sensitive fields
+- [ ] Use RedactedString for extra protection
+- [ ] Use libsodium for production when possible
+- [ ] Validate encryption at startup
+- [ ] Test encryption round-trips
+
+### Operations
+
+- [ ] Regular key rotation schedule
+- [ ] Monitor decryption failures
+- [ ] Log field access patterns for auditing purposes

data/lib/familia/base.rb

@@ -14,7 +14,8 @@ module Familia
   # @see Familia::DataType
   #
   module Base
-    @features = nil
+    @features_available = nil
+    @feature_definitions = nil
     @dump_method = :to_json
     @load_method = :from_json
 
@@ -29,43 +30,33 @@ module Familia
     end
 
     class << self
-      attr_reader :features
+      attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method
 
-      def add_feature(klass, methname)
-        @features ||= {}
-        Familia.ld "[#{self}] Adding feature #{klass} as #{methname.inspect}"
+      def add_feature(klass, feature_name, depends_on: [])
+        @features_available ||= {}
+        Familia.ld "[#{self}] Adding feature #{klass} as #{feature_name.inspect}"
 
-        features[methname] = klass
-      end
-    end
+        # Create field definition object
+        feature_def = FeatureDefinition.new(
+          name: feature_name,
+          depends_on: depends_on,
+        )
 
-    # Base implementation of update_expiration that maintains API compatibility
-    # with the :expiration feature's implementation.
-    #
-    # This is a no-op implementation that gets overridden by features like
-    # :expiration. It accepts an optional default_expiration parameter to maintain interface
-    # compatibility with the overriding implementations.
-    #
-    # @param default_expiration [Integer, nil] Time To Live in seconds (ignored in base implementation)
-    # @return [nil] Always returns nil
-    #
-    # @note This is a no-op implementation. Classes that need expiration
-    #       functionality should include the :expiration feature.
-    #
-    def update_expiration(default_expiration: nil)
-      Familia.ld "[update_expiration] Feature not enabled for #{self.class}. Key: #{dbkey} (caller: #{caller(1..1)})"
-      nil
+        # Track field definitions after defining field methods
+        @feature_definitions ||= {}
+        @feature_definitions[feature_name] = feature_def
+
+        features_available[feature_name] = klass
+      end
     end
 
     def generate_id
-      @identifier ||= Familia.generate_id
-      @identifier
+      @identifier ||= Familia.generate_id # rubocop:disable Naming/MemoizedInstanceVariableName
     end
 
     def uuid
       @uuid ||= SecureRandom.uuid
-      @uuid
     end
   end
 end

data/lib/familia/connection.rb

@@ -106,18 +106,19 @@ module Familia
         # Always pass normalized URI with database to provider
         # Provider MUST return connection already on the correct database
         parsed_uri = normalize_uri(uri)
-        connection = connection_provider.call(parsed_uri.to_s)
+        client = connection_provider.call(parsed_uri.to_s)
 
         # In debug mode, verify the provider honored the contract
-        if Familia.debug? && connection.respond_to?(:client)
-          current_db = connection.client.db
+        if Familia.debug? && client.respond_to?(:client)
+          current_db = client.connection[:db]
           expected_db = parsed_uri.db || 0
+          Familia.ld "Connection provider returned client on DB #{current_db}, expected #{expected_db}"
           if current_db != expected_db
-            Familia.warn "Connection provider returned connection on DB #{current_db}, expected #{expected_db}"
+            Familia.warn "Connection provider returned client on DB #{current_db}, expected #{expected_db}"
           end
         end
 
-        return connection
+        return client
       end
 
       # Third priority: Fallback behavior or error

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

@@ -1,11 +1,9 @@
-# lib/familia/datatype/commands.rb
+# lib/familia/data_type/commands.rb
 
 class Familia::DataType
-
   # Must be included in all DataType classes to provide Redis
   # commands. The class must have a dbkey method.
   module Commands
-
     def move(logical_database)
       dbclient.move dbkey, logical_database
     end
@@ -52,8 +50,7 @@ class Familia::DataType
     end
 
     def echo(meth, trace)
-      dbclient.echo "[#{self.class}\##{meth}] #{trace} (#{@opts[:class]}\#)"
+      dbclient.echo "[#{self.class}##{meth}] #{trace} (#{@opts[:class]}#)"
     end
-
   end
 end

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

@@ -1,9 +1,7 @@
-# lib/familia/datatype/serialization.rb
+# lib/familia/data_type/serialization.rb
 
 class Familia::DataType
-
   module Serialization
-
     # Serializes a value for storage in Redis.
     #
     # @param val [Object] The value to be serialized.
@@ -33,7 +31,7 @@ class Familia::DataType
 
       if opts[:class]
         prepared = Familia.distinguisher(opts[:class], strict_values: strict_values)
-        Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared||'<nil>'}"
+        Familia.ld "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
       end
 
       if prepared.nil?
@@ -42,9 +40,12 @@ class Familia::DataType
         Familia.ld "  from <#{val.class}> => <#{prepared.class}>"
       end
 
-      Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>", caller(1..1) if Familia.debug?
+      if Familia.debug?
+        Familia.trace :TOREDIS, dbclient, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>",
+                      caller(1..1)
+      end
 
-      Familia.warn "[#{self.class}\#serialize_value] nil returned for #{opts[:class]}\##{name}" if prepared.nil?
+      Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
       prepared
     end
 
@@ -88,9 +89,7 @@ class Familia::DataType
         next if obj.nil?
 
         val = @opts[:class].send load_method, obj
-        if val.nil?
-          Familia.ld "[#{self.class}\#deserialize_values] nil returned for #{@opts[:class]}\##{name}"
-        end
+        Familia.ld "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
 
         val
       rescue StandardError => e
@@ -125,5 +124,4 @@ class Familia::DataType
       ret&.first # return the object or nil
     end
   end
-
 end

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

@@ -1,4 +1,4 @@
-# lib/familia/datatype/types/hashkey.rb
+# lib/familia/data_type/types/hashkey.rb
 
 module Familia
   class HashKey < DataType
@@ -55,7 +55,7 @@ module Familia
     end
 
     def hgetall
-      dbclient.hgetall(dbkey).each_with_object({}) do |(k,v), ret|
+      dbclient.hgetall(dbkey).each_with_object({}) do |(k, v), ret|
         ret[k] = deserialize_value v
       end
     end

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

@@ -1,8 +1,7 @@
-# lib/familia/datatype/types/list.rb
+# lib/familia/data_type/types/list.rb
 
 module Familia
   class List < DataType
-
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def element_count
@@ -91,36 +90,36 @@ module Familia
       rangeraw 0, count
     end
 
-    def each(&blk)
-      range.each(&blk)
+    def each(&)
+      range.each(&)
     end
 
-    def each_with_index(&blk)
-      range.each_with_index(&blk)
+    def each_with_index(&)
+      range.each_with_index(&)
     end
 
-    def eachraw(&blk)
-      rangeraw.each(&blk)
+    def eachraw(&)
+      rangeraw.each(&)
     end
 
-    def eachraw_with_index(&blk)
-      rangeraw.each_with_index(&blk)
+    def eachraw_with_index(&)
+      rangeraw.each_with_index(&)
     end
 
-    def collect(&blk)
-      range.collect(&blk)
+    def collect(&)
+      range.collect(&)
     end
 
-    def select(&blk)
-      range.select(&blk)
+    def select(&)
+      range.select(&)
     end
 
-    def collectraw(&blk)
-      rangeraw.collect(&blk)
+    def collectraw(&)
+      rangeraw.collect(&)
     end
 
-    def selectraw(&blk)
-      rangeraw.select(&blk)
+    def selectraw(&)
+      rangeraw.select(&)
     end
 
     def at(idx)

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

@@ -1,4 +1,4 @@
-# lib/familia/datatype/types/sorted_set.rb
+# lib/familia/data_type/types/sorted_set.rb
 
 module Familia
   class SortedSet < DataType
@@ -99,36 +99,36 @@ module Familia
       revrangeraw 0, count, opts
     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 range(sidx, eidx, opts = {})

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

@@ -1,4 +1,4 @@
-# lib/familia/datatype/types/string.rb
+# lib/familia/data_type/types/string.rb
 
 module Familia
   class String < DataType
@@ -25,6 +25,7 @@ module Familia
 
     def to_s
       return super if value.to_s.empty?
+
       value.to_s
     end