familia 2.0.0.pre10 → 2.0.0.pre13

data/docs/migrating/v2.0.0-pre12.md

@@ -0,0 +1,306 @@
+# Migrating Guide: v2.0.0-pre12
+
+This version introduces significant security improvements to Familia's identifier system, including verifiable identifiers with HMAC signatures, scoped identifier namespaces, and hardened external identifier derivation to prevent potential security vulnerabilities.
+
+## VerifiableIdentifier Feature
+
+### Overview
+
+The new `Familia::VerifiableIdentifier` module allows applications to create and verify identifiers with embedded HMAC signatures. This enables stateless confirmation that an identifier was generated by your application, preventing forged IDs from malicious sources.
+
+### Basic Usage
+
+```ruby
+class Customer < Familia::Horreum
+  feature :verifiable_identifier
+
+  # Required: Set the HMAC secret (do this once in your app initialization)
+  # Generate with: SecureRandom.hex(64)
+  ENV['VERIFIABLE_ID_HMAC_SECRET'] = 'your_64_character_hex_secret'
+end
+
+# Generate a verifiable identifier
+customer = Customer.new
+verifiable_id = customer.generate_verifiable_id
+# => "cust_1234567890abcdef_a1b2c3d4e5f6789..."
+
+# Verify the identifier later (stateless verification)
+if Customer.verified_identifier?(verifiable_id)
+  # Identifier is valid and was generated by this application
+  original_id = Customer.extract_identifier(verifiable_id)
+  customer = Customer.new(original_id)
+else
+  # Identifier is forged or corrupted
+  raise SecurityError, "Invalid identifier"
+end
+```
+
+### Scoped VerifiableIdentifier
+
+The new `scope` parameter enables cryptographically isolated identifier namespaces for multi-tenant, multi-domain, or multi-environment applications.
+
+#### Before (Global Scope)
+```ruby
+# All identifiers share the same cryptographic space
+admin_id = admin.generate_verifiable_id
+user_id = user.generate_verifiable_id
+
+# Risk: Cross-contamination between different contexts
+```
+
+#### After (Scoped Namespaces)
+```ruby
+# Production environment
+prod_customer_id = customer.generate_verifiable_id(scope: 'production')
+prod_admin_id = admin.generate_verifiable_id(scope: 'production:admin')
+
+# Development environment
+dev_customer_id = customer.generate_verifiable_id(scope: 'development')
+
+# Multi-tenant application
+tenant_a_id = user.generate_verifiable_id(scope: "tenant:#{tenant_a.id}")
+tenant_b_id = user.generate_verifiable_id(scope: "tenant:#{tenant_b.id}")
+
+# Verification requires matching scope
+Customer.verified_identifier?(prod_customer_id, scope: 'production')  # => true
+Customer.verified_identifier?(prod_customer_id, scope: 'development') # => false
+```
+
+**Scope Benefits:**
+- **Multi-tenant isolation**: Tenant A cannot forge identifiers for Tenant B
+- **Environment separation**: Production IDs cannot be used in development
+- **Role-based security**: Admin scopes separate from user scopes
+- **Full backward compatibility**: Existing code without scopes continues to work
+
+### Key Management
+
+#### Secure Secret Generation
+```ruby
+# Generate a cryptographically secure HMAC secret
+require 'securerandom'
+secret = SecureRandom.hex(64)  # 512-bit secret
+puts "VERIFIABLE_ID_HMAC_SECRET=#{secret}"
+```
+
+#### Environment Configuration
+```ruby
+# config/application.rb or equivalent
+# Set this BEFORE any VerifiableIdentifier usage
+ENV['VERIFIABLE_ID_HMAC_SECRET'] = Rails.application.credentials.verifiable_id_secret
+
+# Or configure programmatically
+Familia::VerifiableIdentifier.hmac_secret = your_secret_string
+```
+
+## ObjectIdentifier Feature Improvements
+
+### Method Renaming
+
+Method names have been updated for clarity and consistency:
+
+#### Before
+```ruby
+customer = Customer.new
+objid = customer.generate_objid           # Unclear what this generates
+extid = Customer.generate_extid(objid)    # Less secure class method
+```
+
+#### After
+```ruby
+customer = Customer.new
+objid = customer.generate_object_identifier    # Clear: generates object ID
+extid = customer.derive_external_identifier    # Clear: derives from objid, instance method
+```
+
+**Migration:**
+- Replace `generate_objid` → `generate_object_identifier`
+- Replace `generate_external_identifier` → `derive_external_identifier`
+- Remove usage of `generate_extid` (deprecated for security reasons)
+
+### Provenance Tracking
+
+ObjectIdentifier now tracks which generator was used for each identifier:
+
+```ruby
+class Customer < Familia::Horreum
+  feature :object_identifier
+
+  # Configure generator type
+  object_identifier_generator :uuid_v7  # or :uuid_v4, :hex, custom proc
+end
+
+customer = Customer.new
+objid = customer.generate_object_identifier
+
+# Provenance information available
+puts customer.object_identifier_generator_type  # => :uuid_v7
+puts customer.objid_format                     # => :uuid (normalized format)
+```
+
+**Benefits:**
+- **Security auditing**: Know which generator created each identifier
+- **Format normalization**: Eliminates ambiguity between UUID and hex formats
+- **Migration support**: Track mixed generator usage during transitions
+
+## ExternalIdentifier Security Hardening
+
+### Provenance Validation
+
+ExternalIdentifier now validates that objid values come from the ObjectIdentifier feature before deriving external identifiers.
+
+#### Before (Potential Security Risk)
+```ruby
+# Could derive external IDs from any string, including malicious input
+extid = customer.derive_external_identifier("malicious_input")
+```
+
+#### After (Hardened)
+```ruby
+customer = Customer.new
+customer.generate_object_identifier  # Must generate objid first
+
+# Only works with validated objid from ObjectIdentifier feature
+extid = customer.derive_external_identifier  # Secure: uses validated objid
+```
+
+### Improved Security Model
+
+External identifiers are now derived using the internal objid as a seed for a new random value, rather than directly deriving from objid.
+
+#### Before
+```ruby
+# Direct derivation could leak information about objid
+extid = hash(objid)  # Information leakage risk
+```
+
+#### After
+```ruby
+# objid used as seed for new random value
+extid = secure_hash(objid + additional_entropy)  # No information leakage
+```
+
+### Error Handling Improvements
+
+External identifier now raises clear errors for invalid usage:
+
+```ruby
+class Customer < Familia::Horreum
+  feature :external_identifier  # Missing: object_identifier dependency
+end
+
+customer = Customer.new
+# Raises ExternalIdentifierError instead of returning nil
+customer.derive_external_identifier
+# => Familia::ExternalIdentifierError: Model does not have an objid field
+```
+
+## Migration Steps
+
+### 1. Update Method Names
+
+Replace deprecated method names in your codebase:
+
+```bash
+# Search and replace patterns:
+grep -r "generate_objid" --include="*.rb" .
+# Replace with: generate_object_identifier
+
+grep -r "generate_external_identifier" --include="*.rb" .
+# Replace with: derive_external_identifier
+
+grep -r "generate_extid" --include="*.rb" .
+# Remove usage - use derive_external_identifier instead
+```
+
+### 2. Add HMAC Secret for VerifiableIdentifier
+
+If you plan to use VerifiableIdentifier:
+
+```ruby
+# Generate secret
+require 'securerandom'
+secret = SecureRandom.hex(64)
+
+# Add to your environment configuration
+# .env, Rails credentials, or similar
+VERIFIABLE_ID_HMAC_SECRET=your_generated_secret
+
+# Verify configuration
+puts ENV['VERIFIABLE_ID_HMAC_SECRET']&.length  # Should be 128 characters
+```
+
+### 3. Update ExternalIdentifier Usage
+
+Ensure proper dependency chain:
+
+```ruby
+class YourModel < Familia::Horreum
+  # Required: ObjectIdentifier must come before ExternalIdentifier
+  feature :object_identifier
+  feature :external_identifier
+
+  # Configure generator if needed
+  object_identifier_generator :uuid_v7
+end
+
+# Usage pattern
+model = YourModel.new
+model.generate_object_identifier  # Generate objid first
+extid = model.derive_external_identifier  # Then derive external ID
+```
+
+### 4. Review Security-Sensitive Code
+
+Audit any code that processes identifiers from external sources:
+
+```ruby
+# Before: Potentially unsafe
+def process_identifier(external_id)
+  # Could process forged identifiers
+  model = Model.find_by_external_id(external_id)
+end
+
+# After: With verification
+def process_identifier(verifiable_id)
+  # Verify identifier authenticity first
+  unless Model.verified_identifier?(verifiable_id)
+    raise SecurityError, "Invalid identifier"
+  end
+
+  original_id = Model.extract_identifier(verifiable_id)
+  model = Model.new(original_id)
+end
+```
+
+## Breaking Changes
+
+1. **`generate_extid` removed** - Use instance-level `derive_external_identifier` instead
+2. **ExternalIdentifier validation** - Now raises `ExternalIdentifierError` instead of returning `nil` for models without objid
+3. **Method names changed** - `generate_objid` → `generate_object_identifier`, `generate_external_identifier` → `derive_external_identifier`
+
+## New Security Capabilities
+
+1. **Cryptographic identifier verification** - Prevent forged IDs with HMAC signatures
+2. **Scoped namespaces** - Isolate identifiers by tenant, environment, or role
+3. **Provenance tracking** - Know which generator created each identifier
+4. **Information leakage prevention** - External IDs no longer directly expose internal IDs
+5. **Input validation** - Clear error messages for invalid operations
+
+## Testing Your Migration
+
+```ruby
+# Test ObjectIdentifier changes
+model = YourModel.new
+objid = model.generate_object_identifier
+extid = model.derive_external_identifier
+puts "Generator: #{model.object_identifier_generator_type}"
+
+# Test VerifiableIdentifier (if using)
+vid = model.generate_verifiable_id
+puts "Verifiable: #{YourModel.verified_identifier?(vid)}"
+
+# Test scoped identifiers (if using)
+scoped_vid = model.generate_verifiable_id(scope: 'production')
+puts "Scoped valid: #{YourModel.verified_identifier?(scoped_vid, scope: 'production')}"
+puts "Wrong scope: #{YourModel.verified_identifier?(scoped_vid, scope: 'development')}"
+```

data/docs/migrating/v2.0.0-pre13.md

@@ -0,0 +1,329 @@
+# Migrating Guide: v2.0.0-pre13
+
+This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects through automatic discovery and loading of feature-specific configuration files.
+
+## Feature-Specific Autoloading System
+
+### Overview
+
+The new autoloading system allows features to automatically discover and load extension files from your project directories. When you include a feature in your model, Familia now searches for configuration files using conventional patterns, enabling clean separation between core model definitions and feature-specific configurations.
+
+### Basic Usage
+
+#### Before (Manual Configuration)
+```ruby
+# app/models/user.rb
+class User < Familia::Horreum
+  field :name, :email, :password
+
+  feature :safe_dump
+  # All configuration had to be done in the same file
+  safe_dump_fields :name, :email  # password excluded for security
+end
+```
+
+#### After (Automatic Discovery)
+```ruby
+# app/models/user.rb - Clean model definition
+class User < Familia::Horreum
+  field :name, :email, :password
+  feature :safe_dump  # ← Triggers autoloading
+end
+
+# app/models/user/safe_dump_extensions.rb - Automatically loaded
+class User
+  safe_dump_fields :name, :email  # password excluded for security
+end
+```
+
+### File Naming Conventions
+
+The autoloading system follows these patterns for discovering extension files:
+
+#### Pattern: `{model_name}/{feature_name}_*.rb`
+
+**Example Structures:**
+```
+app/models/
+├── user.rb                              # Main model
+├── user/
+│   ├── safe_dump_extensions.rb          # SafeDump configuration
+│   ├── safe_dump_custom.rb              # Additional SafeDump setup
+│   └── relationships_config.rb          # Relationships configuration
+├── product.rb                           # Another model
+└── product/
+    ├── safe_dump_fields.rb              # Product's SafeDump config
+    └── expiration_settings.rb           # Expiration configuration
+```
+
+#### Supported Patterns
+- `safe_dump_extensions.rb`
+- `safe_dump_*.rb` (any filename starting with the feature name)
+- `expiration_config.rb`
+- `relationships_setup.rb`
+
+### Advanced Configuration Examples
+
+#### Complex SafeDump Setup
+```ruby
+# app/models/customer.rb
+class Customer < Familia::Horreum
+  field :first_name, :last_name, :email, :phone
+  field :credit_card_number, :ssn, :internal_notes
+
+  feature :safe_dump
+end
+
+# app/models/customer/safe_dump_configuration.rb
+class Customer
+  # Define which fields are safe for API responses
+  safe_dump_fields :first_name, :last_name, :email
+
+  # Custom serialization for specific fields
+  def safe_dump_email
+    email&.downcase
+  end
+
+  # Computed fields for API
+  def safe_dump_full_name
+    "#{first_name} #{last_name}".strip
+  end
+end
+```
+
+#### Multi-Feature Organization
+```ruby
+# app/models/session.rb
+class Session < Familia::Horreum
+  field :user_id, :token, :ip_address, :user_agent
+
+  feature :safe_dump
+  feature :expiration
+end
+
+# app/models/session/safe_dump_api.rb
+class Session
+  safe_dump_fields :user_id, :ip_address
+  # token excluded for security
+end
+
+# app/models/session/expiration_policy.rb
+class Session
+  # Sessions expire after 24 hours
+  def self.default_ttl
+    24 * 60 * 60
+  end
+
+  # Cascade expiration to related data
+  cascade_expiration_to :user_sessions
+end
+```
+
+### Consolidated Autoloader Architecture
+
+#### Familia::Autoloader
+
+The new `Familia::Autoloader` class provides a shared utility for consistent file loading patterns across the framework:
+
+```ruby
+# Internal usage example (you typically won't call this directly)
+autoloader = Familia::Autoloader.new(
+  base_class: User,
+  feature_name: :safe_dump,
+  search_patterns: ['user/safe_dump_*.rb']
+)
+
+# Discovers and loads matching files
+autoloader.discover_and_load_extensions
+```
+
+#### Autoloading Strategies
+
+The autoloader supports multiple discovery strategies:
+
+1. **Directory-based**: Search in conventional directories
+2. **Pattern-based**: Use glob patterns for flexible matching
+3. **Explicit paths**: Load specific files when found
+
+### How Autoloading Works
+
+#### Discovery Process
+
+1. **Feature Activation**: When `feature :safe_dump` is called
+2. **Path Resolution**: Autoloader determines search paths based on model location
+3. **Pattern Matching**: Searches for files matching `{model_name}/{feature_name}_*.rb`
+4. **File Loading**: Loads discovered files in alphabetical order
+5. **Extension Application**: Feature-specific methods become available
+
+#### Search Locations
+
+The autoloader searches in these locations (in order):
+
+```ruby
+# If your model is in app/models/user.rb, it searches:
+[
+  'app/models/user/',           # Same directory as model
+  'lib/user/',                  # Lib directory
+  'config/models/user/',        # Config directory
+  './user/'                     # Current directory
+]
+```
+
+### Migration Steps
+
+#### 1. Reorganize Existing Models
+
+Move feature-specific configuration to separate files:
+
+```bash
+# Create directories for feature configurations
+mkdir -p app/models/user
+mkdir -p app/models/product
+mkdir -p app/models/order
+
+# Move configurations
+# From app/models/user.rb, extract safe_dump configuration to:
+# app/models/user/safe_dump_extensions.rb
+```
+
+#### 2. Update Model Files
+
+Clean up your main model files:
+
+```ruby
+# Before: Everything in one file
+class User < Familia::Horreum
+  field :name, :email, :password, :role
+
+  feature :safe_dump
+  safe_dump_fields :name, :email
+
+  feature :expiration
+  def self.default_ttl
+    86400
+  end
+end
+
+# After: Clean separation
+class User < Familia::Horreum
+  field :name, :email, :password, :role
+
+  feature :safe_dump    # Configuration auto-loaded
+  feature :expiration   # Configuration auto-loaded
+end
+```
+
+#### 3. Create Extension Files
+
+Set up your feature-specific configurations:
+
+```ruby
+# app/models/user/safe_dump_extensions.rb
+class User
+  safe_dump_fields :name, :email
+  # password and role excluded for security
+end
+
+# app/models/user/expiration_config.rb
+class User
+  def self.default_ttl
+    86400  # 24 hours
+  end
+end
+```
+
+### Benefits of the New System
+
+#### Code Organization
+- **Separation of Concerns**: Feature logic separated from core model definition
+- **Maintainability**: Easier to find and modify feature-specific code
+- **Readability**: Core models are cleaner and more focused
+
+#### Team Development
+- **Reduced Conflicts**: Multiple developers can work on different features without merge conflicts
+- **Feature Ownership**: Clear boundaries for feature-specific code
+- **Testing**: Easier to test features in isolation
+
+#### Scalability
+- **Large Models**: Complex models remain manageable
+- **Feature Growth**: New features can be added without bloating main model files
+- **Refactoring**: Easier to extract and reorganize feature code
+
+### Debugging Autoloading
+
+#### Enable Debug Output
+
+```ruby
+# In your application initialization
+ENV['FAMILIA_DEBUG'] = '1'
+
+# Or programmatically
+Familia::Features::Autoloadable.debug = true
+```
+
+#### Debug Output Example
+```
+[Familia::Autoloader] Searching for User safe_dump extensions...
+[Familia::Autoloader] Found: app/models/user/safe_dump_extensions.rb
+[Familia::Autoloader] Loading: app/models/user/safe_dump_extensions.rb
+[Familia::Autoloader] SafeDump extension loaded successfully for User
+```
+
+#### Troubleshooting
+
+**Common Issues:**
+
+1. **File Not Found**: Ensure file naming follows the `{feature_name}_*.rb` pattern
+2. **Load Order**: Files are loaded alphabetically; prefix with numbers if order matters
+3. **Class Scope**: Extension files should reopen the same class as your model
+
+**Validation:**
+```ruby
+# Check if autoloading worked
+User.respond_to?(:safe_dump_field_names)  # => true
+User.safe_dump_field_names                # => [:name, :email]
+```
+
+### Backward Compatibility
+
+The autoloading system is fully backward compatible:
+
+- **Existing Models**: Continue to work without changes
+- **Manual Configuration**: Still supported alongside autoloading
+- **Gradual Migration**: You can migrate models one at a time
+
+### Performance Considerations
+
+- **Load Time**: Files are loaded once during feature activation
+- **Memory Usage**: No additional memory overhead after loading
+- **Caching**: Discovered files are cached to avoid repeated filesystem scans
+
+### Testing Your Migration
+
+```ruby
+# Test that autoloading is working
+class TestUser < Familia::Horreum
+  field :name, :email
+  feature :safe_dump
+end
+
+# Verify extension methods are available
+puts TestUser.respond_to?(:safe_dump_field_names)
+puts TestUser.safe_dump_field_names.inspect
+
+# Test instance methods
+user = TestUser.new(name: "John", email: "john@example.com")
+puts user.safe_dump.inspect
+```
+
+## New Capabilities
+
+1. **Automatic Extension Discovery**: No manual require statements needed
+2. **Conventional File Organization**: Standard patterns for consistent project structure
+3. **Feature Isolation**: Clean separation between core models and feature configurations
+4. **Shared Autoloader Infrastructure**: Consistent loading behavior across all features
+5. **Debug Support**: Built-in debugging for troubleshooting autoloading issues
+
+## Breaking Changes
+
+**None** - This release is fully backward compatible. Existing models and feature configurations continue to work without modification.