otto 2.9.0 → 2.10.0

data/docs/ipaddr-encoding-quirk.md

@@ -1,34 +0,0 @@
-# IPAddr#to_s Encoding Quirk in Ruby 3
-
-Ruby's `IPAddr#to_s` returns inconsistent encodings: IPv4 addresses use US-ASCII, IPv6 addresses use UTF-8.
-
-## Behavior
-
-```ruby
-IPAddr.new('192.168.1.1').to_s.encoding  # => #<Encoding:US-ASCII>
-IPAddr.new('::1').to_s.encoding          # => #<Encoding:UTF-8>
-```
-
-## Cause
-
-Different string construction in IPAddr's `_to_string` method:
-
-- **IPv4**: `Array#join('.')` → US-ASCII optimization
-- **IPv6**: `String#%` → UTF-8 default
-
-## Impact
-
-- Rack expects UTF-8 strings
-- Mixed encodings cause `Encoding::CompatibilityError`
-- String operations fail on encoding mismatches
-
-## Solution
-
-Use `force_encoding('UTF-8')` instead of `encode('UTF-8')`:
-
-- IP addresses contain only ASCII characters
-- ASCII bytes are identical in US-ASCII and UTF-8
-- `force_encoding` changes label only (O(1))
-- `encode` creates new string (O(n))
-
-This ensures consistent UTF-8 encoding across all IP strings.

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

@@ -1,276 +0,0 @@
-# Migrating to Otto v2.0.0-pre1
-
-## What's New in v2.0.0-pre1
-
-This pre-release includes extensive test coverage improvements (76 new test cases), core module refactoring, middleware stack unification, and a major update to Logic class authentication patterns. See the [full changelog](../../CHANGELOG.rst#changelog-2.0.0-pre1) for complete details.
-
-The main breaking changes affect:
-1. Applications that directly manipulate the middleware stack
-2. Logic classes using the old authentication signature
-
-## Middleware Stack Unified API
-
-Otto v2.0.0-pre1 introduces a significant refactoring of the middleware stack management, providing a more consistent and efficient approach to middleware configuration.
-
-### Key Changes
-
-#### Unified Middleware Registration
-
-Previous versions had separate legacy and new middleware stacks. In v2.0.0-pre1, we've consolidated these into a single, more powerful middleware stack.
-
-**Before:**
-```ruby
-# Old approach with separate stacks
-otto.middleware_stack << SomeMiddleware
-otto.middleware.add(AnotherMiddleware)
-```
-
-**After:**
-```ruby
-# Unified middleware registration
-otto.use(SomeMiddleware)
-otto.use(AnotherMiddleware)
-```
-
-#### Performance Improvements
-
-- Middleware lookup is now O(1) using a Set
-- Memoized middleware list reduces repeated array creation
-- Prevent duplicate middleware registrations with identical configurations
-
-### Migration Steps
-
-1. Replace all `otto.middleware_stack <<` calls with `otto.use()`
-2. Remove any direct references to `otto.middleware_stack`
-3. Use `otto.middleware.includes?()` instead of manual stack checks
-
-### Authentication and Security Methods
-
-Authentication and security methods now consistently use the new unified middleware stack:
-
-```ruby
-# Before
-otto.middleware_stack << Otto::Security::CSRFMiddleware
-
-# After (no change needed)
-otto.enable_csrf_protection!
-```
-
-### Performance Considerations
-
-The new implementation is more memory-efficient and provides faster middleware lookups, especially for applications with many middleware components.
-
-### Potential Breaking Changes
-
-- Code relying on direct manipulation of `middleware_stack` will need updates
-- Method signatures for middleware configuration remain the same
-
-### Example Migration
-
-```ruby
-# Old code
-class MyApp
-  def initialize
-    @otto = Otto.new
-    @otto.middleware_stack << CustomMiddleware
-    @otto.middleware.add(AnotherMiddleware)
-  end
-end
-
-# New code
-class MyApp
-  def initialize
-    @otto = Otto.new
-    @otto.use(CustomMiddleware)
-    @otto.use(AnotherMiddleware)
-  end
-end
-```
-
-### Troubleshooting
-
-If you encounter any issues with middleware registration or configuration, please file an issue at [Otto GitHub Repository](https://github.com/delano/otto/issues).
-
-## Logic Class RequestContext Pattern
-
-Otto v2.0.0-pre1 introduces a major improvement to Logic class authentication with the new RequestContext pattern.
-
-### Key Changes
-
-#### New Constructor Signature
-
-Logic classes now use a cleaner, more powerful constructor signature that provides immutable context.
-
-**Before:**
-```ruby
-class MyLogic
-  attr_reader :session, :user, :params, :locale
-
-  def initialize(session, user, params, locale)
-    @session = session
-    @user = user
-    @params = params
-    @locale = locale
-  end
-
-  def process
-    return { error: 'not authenticated' } unless @user
-    { result: 'success', user_name: @user['name'] }
-  end
-end
-```
-
-**After:**
-```ruby
-class MyLogic
-  attr_reader :context, :params, :locale
-
-  def initialize(context, params, locale)
-    @context = context
-    @params = params
-    @locale = locale
-  end
-
-  def process
-    return { error: 'not authenticated' } unless @context.authenticated?
-    {
-      result: 'success',
-      user_name: @context.user_name,
-      roles: @context.roles,
-      permissions: @context.permissions
-    }
-  end
-end
-```
-
-#### RequestContext Benefits
-
-1. **Immutable Structure** - RequestContext is a Ruby Data class that can't be accidentally modified
-2. **Helper Methods** - Built-in methods like `authenticated?`, `has_role?`, `has_permission?`
-3. **Cleaner Interface** - Single context parameter instead of separate session/user parameters
-4. **Type Safety** - Better IDE support and documentation
-5. **Future-proof** - New authentication data automatically available
-
-#### RequestContext API
-
-```ruby
-# Authentication status
-context.authenticated?     # Boolean: has non-empty user data
-context.anonymous?         # Boolean: not authenticated
-
-# User information
-context.user_id           # User ID from various possible locations
-context.user_name         # User name/username
-context.session_id        # Session identifier
-
-# Role and permission checks
-context.has_role?('admin')              # Single role check
-context.has_permission?('write')        # Single permission check
-context.has_any_role?('admin', 'mod')   # Multiple role check
-context.roles                           # Array of all user roles
-context.permissions                     # Array of all user permissions
-
-# Raw data access
-context.session          # Session hash
-context.user            # User hash
-context.auth_method     # Authentication method used
-context.metadata        # Additional context data
-```
-
-### Migration Steps
-
-1. **Update Logic class constructor signatures** from 4 parameters to 3:
-   ```ruby
-   # Change this:
-   def initialize(session, user, params, locale)
-
-   # To this:
-   def initialize(context, params, locale)
-   ```
-
-2. **Update instance variables**:
-   ```ruby
-   # Change this:
-   @session = session
-   @user = user
-
-   # To this:
-   @context = context
-   ```
-
-3. **Update authentication checks**:
-   ```ruby
-   # Change this:
-   return error unless @user
-
-   # To this:
-   return error unless @context.authenticated?
-   ```
-
-4. **Update data access**:
-   ```ruby
-   # Change this:
-   user_name = @user&.dig('name')
-   user_role = @user&.dig('role')
-
-   # To this:
-   user_name = @context.user_name
-   user_role = @context.roles.first
-   ```
-
-### Example Migration
-
-**Before (v1.x):**
-```ruby
-class AdminPanel
-  attr_reader :session, :user, :params, :locale
-
-  def initialize(session, user, params, locale)
-    @session = session
-    @user = user
-    @params = params
-    @locale = locale
-  end
-
-  def raise_concerns
-    raise 'Access denied' unless @user&.dig('role') == 'admin'
-  end
-
-  def process
-    {
-      panel: 'admin',
-      user: @user&.dig('name') || 'unknown',
-      session_id: @session&.dig('id')
-    }
-  end
-end
-```
-
-**After (v2.0):**
-```ruby
-class AdminPanel
-  attr_reader :context, :params, :locale
-
-  def initialize(context, params, locale)
-    @context = context
-    @params = params
-    @locale = locale
-  end
-
-  def raise_concerns
-    raise 'Access denied' unless @context.has_role?('admin')
-  end
-
-  def process
-    {
-      panel: 'admin',
-      user: @context.user_name || 'unknown',
-      session_id: @context.session_id,
-      authenticated: @context.authenticated?,
-      permissions: @context.permissions
-    }
-  end
-end
-```
-
-This provides a cleaner, more maintainable interface while giving Logic classes access to rich authentication context.

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

@@ -1,338 +0,0 @@
-# Otto v2.0.0-pre2 Migration Guide
-
-## Overview
-
-This release resolves critical architectural issues with `StrategyResult` semantics and removes deprecated methods. The changes clarify the distinction between "request state" (user in session) and "authentication outcomes" (auth attempt just succeeded).
-
-## Breaking Changes
-
-### 1. StrategyResult Methods Removed
-
-**Removed Methods:**
-- `StrategyResult#success?` - Always returned `true`, meaningless
-- `StrategyResult#failure?` - Always returned `false`, meaningless
-- `FailureResult#success?` - Always returned `false`
-- `FailureResult#failure?` - Always returned `true`
-
-**Migration:**
-
-```ruby
-# Before - checking success/failure
-if strategy_result&.success?
-  # handle success
-end
-
-# After - type checking
-if strategy_result.is_a?(Otto::Security::Authentication::StrategyResult)
-  # handle success
-end
-
-```
-
-### 2. New Semantic Distinction
-
-**New Method:**
-- `StrategyResult#auth_attempt_succeeded?` - Returns `true` only when auth strategy just executed successfully
-
-**Key Semantic Difference:**
-
-| Method | Meaning | Use Case |
-|--------|---------|----------|
-| `authenticated?` | User in session (request state) | Check if session has user |
-| `auth_attempt_succeeded?` | Auth strategy just succeeded (auth outcome) | Post-login redirects, analytics |
-
-**Migration Examples:**
-
-#### Registration Flow (IMPORTANT)
-
-```ruby
-# Before - BROKEN - blocks legitimate registration
-class CreateAccount < Logic::Base
-  def raise_concerns
-    # This was always true if user in session, blocking registration
-    raise OT::FormError, "Already signed up" if @strategy_result.success?
-  end
-end
-
-# After - CORRECT
-class CreateAccount < Logic::Base
-  def raise_concerns
-    # Check if user already in session
-    raise OT::FormError, "Already signed up" if @strategy_result.authenticated?
-  end
-end
-```
-
-#### Post-Login Redirect
-
-```ruby
-# Before - unreliable
-class AuthController
-  def authenticate
-    if @strategy_result.success?  # Always true, not helpful
-      redirect_to dashboard_path
-    end
-  end
-end
-
-# After - correct semantic
-class AuthController
-  def authenticate
-    if @strategy_result.auth_attempt_succeeded?
-      # Only redirect when auth route just succeeded
-      redirect_to dashboard_path
-    end
-  end
-end
-```
-
-## Non-Breaking Enhancements
-
-### 1. Comprehensive Documentation
-
-`StrategyResult` now includes extensive inline documentation:
-- Usage patterns and creation guidelines
-- Session contract for multi-app architectures
-- Examples for common scenarios
-- Clear distinction between request state and auth outcomes
-
-### 2. Session Contract (Multi-App Architectures)
-
-For shared session architectures (Auth app + Core app):
-
-**Required session keys for authenticated state:**
-```ruby
-session['authenticated']     # Boolean flag
-session['identity_id']       # User/customer ID
-session['authenticated_at']  # Timestamp
-```
-
-**Optional session keys:**
-```ruby
-session['email']            # User email
-session['ip_address']       # Client IP (masked by default via IPPrivacyMiddleware)
-session['user_agent']       # Client UA
-session['locale']           # User locale
-```
-
-**Advanced mode adds:**
-```ruby
-session['account_external_id']  # Rodauth external_id
-session['advanced_account_id']  # Rodauth account ID
-```
-
-## Application Code Updates Required
-
-### 1. Remove Manual StrategyResult Creation
-
-**Anti-pattern identified:**
-```ruby
-# BAD - Bypasses Otto's auth_method tracking
-class Controller::Base
-  def _strategy_result
-    Otto::Security::Authentication::StrategyResult.new(
-      session: session,
-      user: cust,
-      auth_method: 'session',  # Hardcoded - loses semantic meaning
-      metadata: { ip: req.masked_ip }  # Uses masked IP (privacy by default)
-    )
-  end
-end
-```
-
-**Correct approach:**
-```ruby
-# GOOD - Use RouteAuthWrapper-provided result
-class Controller::Base
-  def strategy_result
-    req.env['otto.strategy_result']  # Created by RouteAuthWrapper
-  end
-end
-
-# Or for non-auth checks, use session directly
-class Controller::Base
-  def current_user
-    return nil unless session['authenticated']
-    Customer.find(session['identity_id'])
-  end
-end
-```
-
-### 2. Update Logic Classes
-
-**Pattern to check for:**
-```ruby
-# Search your codebase for these patterns:
-grep -r "@strategy_result.success?" apps/
-grep -r "@context.success?" apps/
-grep -r "strategy_result&.success?" apps/
-```
-
-**Update to:**
-- Use `authenticated?` for "user in session" checks (registration, profile access, etc.)
-- Use `auth_attempt_succeeded?` for "just logged in" checks (redirects, welcome messages, etc.)
-
-### 3. Test Updates
-
-**RSpec matchers:**
-```ruby
-# Before
-expect(result).to be_success
-expect(result).to be_failure
-
-# After
-expect(result).to be_a(Otto::Security::Authentication::StrategyResult)
-```
-
-## Architecture Clarifications
-
-### When StrategyResult is Created
-
-1. **Routes WITH `auth=...` requirement:**
-   - RouteAuthWrapper executes strategy
-   - Always returns `StrategyResult` (success or failure)
-   - RouteAuthWrapper returns 401/302 response on `AuthFailure`
-
-2. **Routes WITHOUT `auth=...` requirement:**
-   - No RouteAuthWrapper wrapping
-   - No `StrategyResult` created (routes without auth don't need it)
-
-3. **Auth app (Roda) routes:**
-   - Manually creates `StrategyResult` for Logic class compatibility
-   - Same interface as Otto controllers
-
-### Integration Boundaries
-
-**Multi-app setup (Auth + Core + API):**
-- **Shared:** Session middleware, Redis session, Logic classes, Customer model
-- **Auth app:** Creates StrategyResult manually, uses Roda routing
-- **Core/API apps:** StrategyResult from RouteAuthWrapper
-- **Integration:** Pure session-based, no direct code calls between apps
-
-## Testing Your Migration
-
-### 1. Registration Flow Test
-
-```ruby
-describe "CreateAccount" do
-  it "blocks registration when user already authenticated" do
-    strategy_result = Otto::Security::Authentication::StrategyResult.new(
-      session: { user_id: 123 },
-      user: { id: 123 },
-      auth_method: 'anonymous',  # No auth route, but user in session
-      metadata: {}
-    )
-
-    logic = CreateAccount.new(strategy_result, params, 'en')
-
-    expect { logic.raise_concerns }.to raise_error(OT::FormError, /Already signed up/)
-  end
-end
-```
-
-### 2. Auth Attempt Test
-
-```ruby
-describe "LoginHandler" do
-  it "redirects after successful authentication" do
-    strategy_result = Otto::Security::Authentication::StrategyResult.new(
-      session: { user_id: 123 },
-      user: { id: 123 },
-      auth_method: 'session',  # Auth route succeeded
-      metadata: {}
-    )
-
-    expect(strategy_result.authenticated?).to be true
-    expect(strategy_result.auth_attempt_succeeded?).to be true
-  end
-end
-```
-
-## Checklist
-
-- [ ] Remove all usage of `success?` and `failure?` methods
-- [ ] Update registration flows to use `authenticated?`
-- [ ] Update post-login flows to use `auth_attempt_succeeded?` if needed
-- [ ] Remove manual `StrategyResult` creation in controllers
-- [ ] Update test matchers from `be_success`/`be_failure` to type checks
-- [ ] Verify session contract keys match across apps
-- [ ] Run full test suite: `bundle exec rspec`
-- [ ] Test registration while logged in (should be blocked)
-- [ ] Test login redirect flow (should work correctly)
-
-## Configuration Updates
-
-### Authentication Login Path Configuration
-
-When authentication fails for HTML requests, Otto redirects to a login page. You can configure this path:
-
-```ruby
-# Initialize with login_path configuration
-otto = Otto.new do
-  auth_config[:login_path] = '/auth/login'  # Default: '/signin'
-end
-
-# Or configure after initialization
-otto.auth_config[:login_path] = '/custom/login'
-```
-
-**Note:** If not configured, the default fallback is `/signin`. Ensure this route exists or configure your actual login path to avoid 404 errors on authentication failures.
-
-## Additional Improvements in v2.0.0-pre2
-
-### Middleware Architecture Enhancements
-
-**1. Renamed MCP ValidationMiddleware → SchemaValidationMiddleware**
-- Resolves naming collision with `Otto::Security::ValidationMiddleware`
-- `Otto::MCP::SchemaValidationMiddleware` now clearly indicates JSON schema validation
-- `Otto::Security::ValidationMiddleware` remains for input sanitization
-
-**Migration:**
-```ruby
-# File renamed: lib/otto/mcp/validation.rb → lib/otto/mcp/schema_validation.rb
-# Class renamed automatically if using Otto's MCP server
-# No action needed for most users
-```
-
-**2. Centralized Env Keys Documentation**
-- New file: `lib/otto/env_keys.rb`
-- Documents all `env['otto.*']` keys with types, setters, and users
-- Includes usage examples and multi-app integration patterns
-- Essential reference for custom middleware development
-
-**3. RateLimitMiddleware Clarity**
-- Added documentation clarifying it's a CONFIGURATOR, not enforcer
-- Actual rate limiting happens in Rack::Attack middleware
-- `call` method is explicitly a pass-through
-
-**4. Middleware Order Enforcement**
-- New method: `MiddlewareStack#validate_mcp_middleware_order`
-- New method: `MiddlewareStack#add_with_position` for explicit ordering
-- MCP Server uses explicit positioning: `position: :first` and `position: :last`
-- Validates middleware order and warns if suboptimal
-- Optimal: RateLimitMiddleware → TokenMiddleware → SchemaValidationMiddleware
-- Validation runs automatically when MCP is enabled
-
-**Usage Example:**
-```ruby
-# Explicit positioning for clarity
-middleware.add_with_position(
-  Otto::MCP::RateLimitMiddleware,
-  security_config,
-  position: :first  # Ensures rate limiting runs first
-)
-
-middleware.add_with_position(
-  Otto::MCP::SchemaValidationMiddleware,
-  position: :last  # Ensures validation runs last
-)
-```
-
-## Questions?
-
-Review the comprehensive inline documentation in:
-- `lib/otto/security/authentication/strategy_result.rb` (lines 1-90) - Auth semantics
-- `lib/otto/security/authentication/route_auth_wrapper.rb` - Auth handler wrapper
-- `lib/otto/env_keys.rb` - Complete env key registry
-
-The documentation includes detailed usage patterns, session contracts, and examples for common scenarios.