familia 2.0.0.pre4 → 2.0.0.pre6

data/docs/wiki/Security-Model.md

@@ -0,0 +1,183 @@
+# Security Model
+
+## Cryptographic Design
+
+### Provider-Based Architecture
+
+Familia uses a modular provider system that automatically selects the best available encryption algorithm:
+
+### Encryption Algorithms
+
+**XChaCha20-Poly1305 Provider (Priority: 100)**
+- Requires: `rbnacl` gem (libsodium bindings)
+- Key Size: 256 bits (32 bytes)
+- Nonce Size: 192 bits (24 bytes) - extended nonce space
+- Authentication Tag: 128 bits (16 bytes)
+- Key Derivation: BLAKE2b with personalization string
+
+**AES-256-GCM Provider (Priority: 50)**
+- Requires: OpenSSL (always available)
+- Key Size: 256 bits (32 bytes)
+- Nonce Size: 96 bits (12 bytes) - standard GCM nonce
+- Authentication Tag: 128 bits (16 bytes)
+- Key Derivation: HKDF-SHA256
+
+### 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"
+```
+
+**Provider-Specific KDF:**
+- **XChaCha20-Poly1305**: BLAKE2b with customizable personalization string
+- **AES-256-GCM**: HKDF-SHA256 with salt and info parameters
+
+The personalization string provides cryptographic domain separation:
+```ruby
+Familia.configure do |config|
+  config.encryption_personalization = 'MyApp-2024'  # Default: 'Familia'
+end
+```
+
+### Ciphertext Format
+
+The encrypted data is stored as JSON with algorithm-specific fields:
+
+**XChaCha20-Poly1305:**
+```json
+{
+  "algorithm": "xchacha20poly1305",
+  "nonce": "base64_24_byte_nonce",
+  "ciphertext": "base64_encrypted_data",
+  "auth_tag": "base64_16_byte_tag",
+  "key_version": "v1"
+}
+```
+
+**AES-256-GCM:**
+```json
+{
+  "algorithm": "aes-256-gcm",
+  "nonce": "base64_12_byte_iv",
+  "ciphertext": "base64_encrypted_data",
+  "auth_tag": "base64_16_byte_tag",
+  "key_version": "v1"
+}
+```
+
+## 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
+
+**⚠️ Critical Ruby Memory Limitations:**
+
+Ruby provides **NO** memory safety guarantees for cryptographic secrets. This affects ALL providers:
+
+- **No secure memory wiping**: Ruby cannot guarantee memory zeroing
+- **GC copying**: Garbage collector may copy secrets before cleanup
+- **String operations**: Every `.dup`, `+`, or interpolation creates uncontrolled copies
+- **Memory dumps**: Secrets may persist in swap files or core dumps
+- **Finalizer uncertainty**: `ObjectSpace.define_finalizer` timing is unpredictable
+
+**Provider-Specific Mitigations:**
+
+Both providers attempt best-effort memory clearing:
+- Call `.clear` on sensitive strings after use
+- Set variables to `nil` when done
+- Use finalizers for cleanup (no guarantees)
+
+**Recommendation**: For production systems with high-security requirements, consider:
+- Hardware Security Modules (HSMs)
+- External key management services
+- Languages with manual memory management (C, Rust)
+- Cryptographic appliances with secure enclaves
+
+### 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/docs/wiki/Transient-Fields-Guide.md

@@ -0,0 +1,280 @@
+# Transient Fields Guide
+
+## Overview
+
+Transient fields provide secure handling of sensitive runtime data that should never be persisted to Redis/Valkey. Unlike encrypted fields, transient fields exist only in memory and are automatically wrapped in `RedactedString` for security.
+
+## When to Use Transient Fields
+
+Use transient fields for:
+- API keys and tokens that change frequently
+- Temporary passwords or passphrases
+- Session-specific secrets
+- Any sensitive data that should never touch persistent storage
+- Debug or development secrets that need secure handling
+
+## Basic Usage
+
+### Define Transient Fields
+
+```ruby
+class ApiClient < Familia::Horreum
+  feature :transient_fields
+
+  field :endpoint          # Regular persistent field
+  transient_field :token   # Transient field (not persisted)
+  transient_field :secret, as: :api_secret  # Custom accessor name
+end
+```
+
+### Working with Transient Fields
+
+```ruby
+client = ApiClient.new(
+  endpoint: 'https://api.example.com',
+  token: ENV['API_TOKEN'],
+  secret: ENV['API_SECRET']
+)
+
+# Regular field persists
+client.save
+client.endpoint  # => "https://api.example.com"
+
+# Transient fields are RedactedString instances
+puts client.token  # => "[REDACTED]"
+
+# Access the actual value safely
+client.token.expose do |token|
+  response = HTTP.post(client.endpoint,
+    headers: { 'Authorization' => "Bearer #{token}" }
+  )
+  # Token value is only available within this block
+end
+
+# Explicit cleanup when done
+client.token.clear!
+```
+
+## RedactedString Security
+
+### Automatic Wrapping
+
+All transient field values are automatically wrapped in `RedactedString`:
+
+```ruby
+client = ApiClient.new(token: 'secret123')
+client.token.class  # => RedactedString
+```
+
+### Safe Access Pattern
+
+```ruby
+# ✅ Recommended: Use .expose block
+client.token.expose do |token|
+  # Use token directly without creating copies
+  HTTP.auth("Bearer #{token}")  # Safe
+end
+
+# ✅ Direct access (use carefully)
+raw_token = client.token.value
+# Remember to clear original source if needed
+
+# ❌ Avoid: These create uncontrolled copies
+token_copy = client.token.value.dup      # Creates copy in memory
+interpolated = "Bearer #{client.token}"  # Creates copy via to_s
+```
+
+### Memory Management
+
+```ruby
+# Clear individual fields
+client.token.clear!
+
+# Check if cleared
+client.token.cleared?  # => true
+
+# Accessing cleared values raises error
+client.token.value  # => SecurityError: Value already cleared
+```
+
+## Advanced Features
+
+### Custom Accessor Names
+
+```ruby
+class Service < Familia::Horreum
+  transient_field :api_key, as: :secret_key
+end
+
+service = Service.new(api_key: 'secret123')
+service.secret_key.expose { |key| use_api_key(key) }
+```
+
+### Integration with Encrypted Fields
+
+```ruby
+class SecureService < Familia::Horreum
+  feature :transient_fields
+
+  encrypted_field :long_term_secret    # Persisted, encrypted
+  transient_field :session_token       # Runtime only, not persisted
+  field :public_endpoint               # Normal field
+end
+
+service = SecureService.new(
+  long_term_secret: 'stored encrypted in Redis',
+  session_token: 'temporary runtime secret',
+  public_endpoint: 'https://api.example.com'
+)
+
+service.save
+# Only long_term_secret and public_endpoint are saved to Redis
+# session_token exists only in memory
+```
+
+## RedactedString API Reference
+
+### Core Methods
+
+```ruby
+# Create (usually automatic via transient_field)
+secret = RedactedString.new('sensitive_value')
+
+# Safe access
+secret.expose { |value| use_value(value) }
+
+# Direct access (use with caution)
+value = secret.value
+
+# Cleanup
+secret.clear!
+
+# Status
+secret.cleared?  # => true/false
+```
+
+### Security Methods
+
+```ruby
+# Logging/debugging protection
+puts secret.to_s     # => "[REDACTED]"
+puts secret.inspect  # => "[REDACTED]"
+
+# Equality (object identity only)
+secret1 == secret2   # => false (unless same object)
+
+# Hash (constant for all instances)
+secret.hash  # => Same for all RedactedString instances
+```
+
+## Security Considerations
+
+### Ruby Memory Limitations
+
+**⚠️ Important**: Ruby provides no memory safety guarantees:
+
+- **No secure wiping**: `.clear!` is best-effort only
+- **GC copying**: Garbage collector may duplicate secrets
+- **String operations**: Every manipulation creates copies
+- **Memory persistence**: Secrets may remain in memory indefinitely
+
+### Best Practices
+
+```ruby
+# ✅ Wrap immediately after input
+password = RedactedString.new(params[:password])
+params[:password] = nil  # Clear original reference
+
+# ✅ Use .expose for short operations
+token.expose { |t| api_call(t) }
+
+# ✅ Clear explicitly when done
+token.clear!
+
+# ✅ Avoid string operations that create copies
+token.expose { |t| "Bearer #{t}" }  # Creates copy
+# Better: Pass token directly to methods that need it
+
+# ❌ Don't pass RedactedString to logging
+logger.info "Token: #{token}"  # Still logs "[REDACTED]" but safer to avoid
+
+# ❌ Don't store in instance variables outside field system
+@raw_token = token.value  # Creates uncontrolled copy
+```
+
+### Production Recommendations
+
+For highly sensitive applications, consider:
+- External secrets management (HashiCorp Vault, AWS Secrets Manager)
+- Hardware Security Modules (HSMs)
+- Languages with secure memory handling
+- Encrypted swap and memory protection at OS level
+
+## Integration Examples
+
+### Rails Controller
+
+```ruby
+class ApiController < ApplicationController
+  def authenticate
+    service = ApiService.new(
+      endpoint: params[:endpoint],
+      token: params[:token]  # Auto-wrapped in RedactedString
+    )
+
+    result = service.token.expose do |token|
+      # Token only accessible within this block
+      ExternalAPI.authenticate(token)
+    end
+
+    # Clear token when request is done
+    service.token.clear!
+
+    render json: { status: result }
+  end
+end
+```
+
+### Background Job
+
+```ruby
+class ApiSyncJob
+  def perform(user_id, token)
+    user = User.find(user_id)
+
+    # Wrap external token securely
+    secure_token = RedactedString.new(token)
+    token.clear if token.respond_to?(:clear)  # Clear original
+
+    client = ApiClient.new(token: secure_token)
+
+    begin
+      sync_data(client)
+    ensure
+      client.token.clear!  # Always cleanup
+    end
+  end
+
+  private
+
+  def sync_data(client)
+    client.token.expose do |token|
+      # Use token for API calls
+      fetch_and_process_data(token)
+    end
+  end
+end
+```
+
+## Comparison with Encrypted Fields
+
+| Feature | Encrypted Fields | Transient Fields |
+|---------|------------------|------------------|
+| **Persistence** | Saved to Redis/Valkey | Memory only |
+| **Encryption** | AES/XChaCha20 | None (not stored) |
+| **Use Case** | Long-term secrets | Runtime secrets |
+| **Access** | Automatic decrypt | RedactedString wrapper |
+| **Performance** | Crypto overhead | No crypto operations |
+| **Lifecycle** | Survives restarts | Cleared on restart |
+
+Choose encrypted fields for data that must persist across sessions. Choose transient fields for sensitive runtime data that should never be stored.

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.trace :ADD_FEATURE, klass, feature_name, caller(1..1) if Familia.debug?
 
-        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/data_type/types/counter.rb

@@ -0,0 +1,38 @@
+# lib/familia/data_type/types/counter.rb
+
+module Familia
+  class Counter < String
+    def initialize(*args)
+      super
+      @opts[:default] ||= 0
+    end
+
+    # Enhanced counter semantics
+    def reset(val = 0)
+      set(val).to_s.eql?('OK')
+    end
+
+    def increment_if_less_than(threshold, amount = 1)
+      current = to_i
+      return false if current >= threshold
+
+      incrementby(amount)
+      true
+    end
+
+    def atomic_increment_and_get(amount = 1)
+      incrementby(amount)
+    end
+
+    # Override to ensure integer serialization
+    def value=(val)
+      super(val.to_i)
+    end
+
+    def value
+      super.to_i
+    end
+  end
+end
+
+Familia::DataType.register Familia::Counter, :counter