familia 2.0.0.pre19 → 2.0.0.pre21

data/docs/guides/implementation.md

@@ -1,276 +0,0 @@
-# Implementation Guide
-
-## Architecture Overview
-
-The encrypted fields feature uses a modular provider system with field transformation hooks:
-
-```
-User Input → Field Setter → Provider Selection → Encryption → Valkey/Redis
-Valkey/Redis → 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. 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
-
-The Manager handles encryption/decryption operations with provider delegation:
-
-```ruby
-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
-```
-
-### 3. Provider Interface
-
-All providers implement a common interface:
-
-```ruby
-class Provider
-  ALGORITHM = 'algorithm-name'
-
-  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
-```
-
-### 4. Key Derivation
-
-Each field gets a unique encryption key using provider-specific methods:
-
-```
-Master Key + Field Context → Provider KDF → Field-Specific Key
-
-XChaCha20-Poly1305: BLAKE2b with personalization
-AES-256-GCM:        HKDF-SHA256
-```
-
-## 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 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
-
-```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' }
-])
-```
-
-## 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
-
-### Provider Benchmarking
-
-```ruby
-# 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
-
-**⚠️ 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
-
-```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.dbkey, "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
-- [Migrating Guide](Migrating-Guide) - Upgrade existing fields

data/docs/guides/security-model.md

@@ -1,183 +0,0 @@
-# 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
-- UnsortedSet 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