familia 2.0.0.pre5 → 2.0.0.pre7

data/docs/wiki/Home.md

@@ -1,46 +1,113 @@
-# Familia Encrypted Fields Documentation
+# Familia v2.0 Documentation
 
-Welcome to the Familia encrypted fields feature documentation. This Wiki provides comprehensive guides for implementing field-level encryption in your Familia-based applications.
+Welcome to the comprehensive documentation for Familia v2.0. This wiki covers all major features including security, connection management, architecture, and object relationships.
 
 ## 📚 Documentation Structure
 
-### Essential Reading (Start Here)
+### 🔐 Security & Data Protection
 
-1. **[Encrypted Fields Overview](Encrypted-Fields-Overview.md)** - Quick introduction and basic usage
+1. **[Encrypted Fields Overview](Encrypted-Fields-Overview.md)** - Persistent encrypted storage with modular providers
+2. **[Transient Fields Guide](Transient-Fields-Guide.md)** - Non-persistent secure data handling with RedactedString
+3. **[Security Model](Security-Model.md)** - Cryptographic design and Ruby memory limitations
 
-2. **[Implementation Guide](Implementation-Guide.md)** - Configuration details and advanced usage
+### 🏗️ Architecture & System Design
 
-3. **[API Reference](API-Reference.md)** - Class and method documentation
+4. **[Feature System Guide](Feature-System-Guide.md)** - Modular architecture with dependencies and conflict resolution _(new!)_
+5. **[Connection Pooling Guide](Connection-Pooling-Guide.md)** - Provider pattern for efficient Redis/Valkey pooling _(new!)_
+6. **[Relationships Guide](Relationships-Guide.md)** - Object relationships and membership system _(new!)_
 
-### Deep Dives
+### 🛠️ Implementation & Usage
 
-4. **[Security Model](Security-Model.md)** - Cryptographic design and Protected vs unprotected scenarios
+7. **[Implementation Guide](Implementation-Guide.md)** - Configuration, providers, and advanced usage
+8. **[API Reference](API-Reference.md)** - Complete class and method documentation
 
-### Operations (As Needed)
+### 🚀 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)_
+9. **[Migration Guide](Migration-Guide.md)** - Upgrading existing fields _(coming soon)_
+10. **[Key Management](Key-Management.md)** - Rotation and best practices _(coming soon)_
 
-## 🚀 Quick Start
+## 🚀 Quick Start Examples
 
+### Encrypted Fields (Persistent)
 ```ruby
-# 1. Add encrypted field to your model
 class User < Familia::Horreum
+  feature :encrypted_fields
   encrypted_field :secret_recipe
 end
 
-# 2. Configure encryption key
+# Configure encryption
 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)
 ```
 
+### Feature System (Modular)
+```ruby
+class Customer < Familia::Horreum
+  feature :safe_dump       # API-safe serialization
+  feature :expiration      # TTL support
+  feature :encrypted_fields # Secure storage
+
+  field :name, :email
+  encrypted_field :api_key
+  default_expiration 24.hours
+  safe_dump_fields :name, :email
+end
+```
+
+### Connection Pooling (Performance)
+```ruby
+# Configure connection provider for multi-database pooling
+Familia.connection_provider = lambda do |uri|
+  parsed = URI.parse(uri)
+  pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
+
+  @pools[pool_key] ||= ConnectionPool.new(size: 10) do
+    Redis.new(host: parsed.host, port: parsed.port, db: parsed.db || 0)
+  end
+
+  @pools[pool_key].with { |conn| conn }
+end
+```
+
+### Object Relationships
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+  identifier_field :custid
+  field :custid, :name, :email
+
+  # Customer collections
+  set :domains
+end
+
+class Domain < Familia::Horreum
+  feature :relationships
+  identifier_field :domain_id
+  field :domain_id, :name, :dns_zone
+
+  # Declare membership in customer collections
+  member_of Customer, :domains, type: :set
+end
+
+# Create objects and establish relationships
+customer = Customer.new(custid: "cust123", name: "Acme Corp")
+domain = Domain.new(domain_id: "dom456", name: "acme.com")
+
+# Establish bidirectional relationship
+domain.add_to_customer_domains(customer.custid)
+customer.domains.add(domain.identifier)
+
+# Query relationships
+domain.in_customer_domains?(customer.custid)  # => true
+customer.domains.member?(domain.identifier)   # => true
+```
+
 
 ## Related Resources
 

data/docs/wiki/Implementation-Guide.md

@@ -2,48 +2,88 @@
 
 ## Architecture Overview
 
-The encrypted fields feature extends Familia's existing field system with transformation hooks:
+The encrypted fields feature uses a modular provider system with field transformation hooks:
 
 ```
-User Input → Field Setter → Serialize Transform → Encryption → Redis
-Redis → Decryption → Deserialize Transform → Field Getter → User Output
+User Input → Field Setter → Provider Selection → Encryption → Redis/Valkey
+Redis/Valkey → Algorithm Detection → Decryption → Field Getter → User Output
+```
+
+### Provider Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Manager       │    │    Registry      │    │   Providers     │
+│                 │    │                  │    │                 │
+│ - encrypt()     │───→│ - get()          │───→│ XChaCha20Poly   │
+│ - decrypt()     │    │ - register()     │    │ AES-GCM         │
+│ - derive_key()  │    │ - priority       │    │ (Future: More)  │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
 ```
 
 ## Core Components
 
-### 1. Transform Hooks
+### 1. Registry System
+
+The Registry manages available encryption providers and selects the best one:
+
+```ruby
+module Familia::Encryption::Registry
+  # Auto-register available providers by priority
+  def self.setup!
+
+  # Get provider instance by algorithm
+  def self.get(algorithm)
+
+  # Get highest-priority available provider
+  def self.default_provider
+end
+```
+
+### 2. Manager Class
 
-Fields now support transform callbacks:
+The Manager handles encryption/decryption operations with provider delegation:
 
 ```ruby
-FieldDefinition = Data.define(
-  :field_name,
-  :method_name,
-  :serialize_transform,    # Called before storage
-  :deserialize_transform   # Called after retrieval
-)
+class Familia::Encryption::Manager
+  # Use specific algorithm or auto-select best
+  def initialize(algorithm: nil)
+
+  # Encrypt with context-specific key derivation
+  def encrypt(plaintext, context:, additional_data: nil)
+
+  # Decrypt with automatic algorithm detection
+  def decrypt(encrypted_json, context:, additional_data: nil)
+end
 ```
 
-### 2. Encryption Module
+### 3. Provider Interface
 
-Handles the cryptographic operations:
+All providers implement a common interface:
 
 ```ruby
-module Familia::Encryption
-  # Encrypts with field-specific derived key
-  def self.encrypt(plaintext, context:, additional_data: nil)
+class Provider
+  ALGORITHM = 'algorithm-name'
 
-  # Decrypts and verifies authenticity
-  def self.decrypt(ciphertext, context:, additional_data: nil)
+  def self.available?        # Check if dependencies are met
+  def self.priority          # Higher = preferred (XChaCha20: 100, AES: 50)
+
+  def encrypt(plaintext, key, additional_data)
+  def decrypt(ciphertext, key, nonce, auth_tag, additional_data)
+  def derive_key(master_key, context)
+  def generate_nonce
 end
 ```
 
-### 3. Key Derivation
+### 4. Key Derivation
 
-Each field gets a unique encryption key:
+Each field gets a unique encryption key using provider-specific methods:
 
 ```
-Master Key + Field Context → HKDF/BLAKE2b → Field-Specific Key
+Master Key + Field Context → Provider KDF → Field-Specific Key
+
+XChaCha20-Poly1305: BLAKE2b with personalization
+AES-256-GCM:        HKDF-SHA256
 ```
 
 ## Implementation Steps
@@ -79,14 +119,28 @@ Familia::Encryption.validate_configuration!
 ### Step 3: Generate Keys
 
 ```bash
-# Generate a secure key
-$ familia encryption:generate_key --bits 256
+# Generate a secure 256-bit key (32 bytes)
+$ openssl rand -base64 32
 # => base64_encoded_key_here
 
 # Add to environment
 $ echo "FAMILIA_ENCRYPTION_KEY_V1=base64_encoded_key_here" >> .env
 ```
 
+### Step 4: Install Optional Dependencies
+
+For best security and performance, install RbNaCl:
+
+```bash
+# Add to Gemfile
+gem 'rbnacl', '~> 7.1', '>= 7.1.1'
+
+# Install
+$ bundle install
+```
+
+Without RbNaCl, Familia falls back to OpenSSL AES-256-GCM (still secure but lower priority).
+
 ## Advanced Usage
 
 ### Custom Field Names
@@ -118,24 +172,63 @@ customers = Customer.batch_create([
 ])
 ```
 
+## Provider-Specific Features
+
+### XChaCha20-Poly1305 Provider (Recommended)
+
+```ruby
+# Enable with RbNaCl gem
+gem 'rbnacl', '~> 7.1'
+
+# Benefits:
+# - Extended nonce (192 bits vs 96 bits)
+# - Better resistance to nonce reuse
+# - BLAKE2b key derivation with personalization
+# - Priority: 100 (highest)
+```
+
+### AES-256-GCM Provider (Fallback)
+
+```ruby
+# Always available with OpenSSL
+# - 256-bit keys, 96-bit nonces
+# - HKDF-SHA256 key derivation
+# - Priority: 50
+# - Good compatibility, proven security
+```
+
 ## Performance Optimization
 
-### Request-Scoped Key Caching
+### Provider Benchmarking
 
 ```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
+# Compare provider performance
+results = Familia::Encryption.benchmark(iterations: 1000)
+puts results
+# => {
+#   "xchacha20poly1305" => { time: 0.45, ops_per_sec: 4444, priority: 100 },
+#   "aes-256-gcm"       => { time: 0.52, ops_per_sec: 3846, priority: 50 }
+# }
+```
+
+### Key Derivation Monitoring
+
+```ruby
+# Monitor key derivations (should increment with each operation)
+puts Familia::Encryption.derivation_count.value
+# => 42
+
+# Reset counter for testing
+Familia::Encryption.reset_derivation_count!
 ```
 
 ### Memory Management
 
-With libsodium installed:
-- Keys are automatically wiped from memory
-- Plaintext values cleared after use
+**⚠️ Important**: Ruby provides no memory safety guarantees. See security warnings in provider files.
+
+- Keys are cleared from variables after use (best effort)
+- No protection against memory dumps or GC copying
+- Plaintext exists in Ruby strings during processing
 
 ## Testing