otto 2.0.0.pre1 → 2.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3de0a572bb6389f8e3f6b64d3295630c1d2f9872734d5840c5c2e5dc89f1fd4
-  data.tar.gz: 41caaa99c08d5646d576b5c15d4392757e541ae00218dd7a3831d4532ee7a30c
+  metadata.gz: b6215d43a8ce52d332bc046b6d51e8474c243e804bb146381fcd617fa8aebd1f
+  data.tar.gz: 7d73de1613bdd0f2450c2b3e16c8ef0b7020ce417f38b506c70c9b05d414d561
 SHA512:
-  metadata.gz: bbef30e2f11091b5b74c7c20aeead0b118b22bd5a52b77cc23c8901f8dcc58f9465748b1d3c46ae1c2cf0a75b7736d07248d9150a6b9fe28ddc02ef23543ca83
-  data.tar.gz: 765a1cc021e278ca5ff484dd55e49695176c8aac998a3374677026857c27643c237088347fd3b04bbae69f4d6eae2ffec089bffbb7019f339c43c85f6e035668
+  metadata.gz: 4f04484aadab6fd972ecc261ed7da8291996e1623ae5df198b08550f82afa86e7d651beb7448d75b690b7505ae5d4d8443dd24c2a98bec7bb4621bcbb8b23950
+  data.tar.gz: bdfe655d0f597f92bfacaf89342aa0d026ecf2e89d1975ebc1835b2521a38f3bec8ba57cce94992ab0ac2eae4f01ce0080f849f82d08bb15e3473c8794fa9667

data/.github/workflows/ci.yml

@@ -41,9 +41,10 @@ jobs:
       - uses: actions/checkout@v5
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
+        continue-on-error: ${{ matrix.experimental }}
         with:
           ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
+          bundler-cache: ${{ !matrix.experimental }}
 
       - name: Setup tmate session
         uses: mxschmitt/action-tmate@7b6a61a73bbb9793cb80ad69b8dd8ac19261834c # v3

data/.github/workflows/claude-code-review.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
 

data/.github/workflows/claude.yml

@@ -26,7 +26,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
 

data/.rubocop.yml

@@ -48,7 +48,10 @@ Gemspec/DevelopmentDependencies:
   Enabled: true
 
 Layout/HashAlignment:
-  Enabled: false
+  Enabled: true
+  EnforcedHashRocketStyle: key
+  EnforcedColonStyle: separator
+  EnforcedLastArgumentHashStyle: always_ignore # Changed from ignore_implicit
 
 Lint/Void:
   Enabled: false

data/CHANGELOG.rst

@@ -1,17 +1,65 @@
 CHANGELOG.rst
 =============
 
-All notable changes to Otto are documented here.
-
-The format is based on `Keep a
-Changelog <https://keepachangelog.com/en/1.1.0/>`__, and this project
-adheres to `Semantic
-Versioning <https://semver.org/spec/v2.0.0.html>`__.
+The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`__, and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`__.
 
 .. raw:: html
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre2:
+
+2.0.0.pre2 — 2025-10-11
+=======================
+
+Added
+-----
+
+- Added `StrategyResult` class with improved user model compatibility and cleaner API
+- Helper methods ``authenticated?``, ``has_role?``, ``has_permission?``, ``user_name``, ``session_id`` for cleaner Logic class implementation
+- Added JSON request body parsing support in Logic class handlers
+- Added new modular directory structure under ``lib/otto/security/``
+- Added backward compatibility aliases to maintain existing API compatibility
+- Added proper namespacing for authentication components and middleware classes
+
+Changed
+-------
+
+- **BREAKING**: Logic class constructor signature changed from ``initialize(session, user, params, locale)`` to ``initialize(context, params, locale)``
+- Logic classes now receive an immutable context object instead of separate session/user parameters
+- LogicClassHandler simplified to single arity pattern, removing backward compatibility code
+- Authentication middleware now creates `StrategyResult` instances for all requests
+- Replaced `RequestContext` with `StrategyResult` class for better authentication handling
+- Simplified authentication strategy API to return `StrategyResult` or `nil` for success/failure
+- Enhanced route handlers to support JSON request body parsing
+- Updated authentication middleware to use `StrategyResult` throughout
+- Reorganized Otto security module structure for better maintainability and separation of concerns
+- Moved authentication strategies to ``Otto::Security::Authentication::Strategies`` namespace
+- Moved security middleware to ``Otto::Security::Middleware`` namespace
+- Moved ``StrategyResult`` and ``FailureResult`` to ``Otto::Security::Authentication`` namespace
+
+Removed
+-------
+
+- Removed `RequestContext` class (which was introduced and then replaced by `StrategyResult` during this development cycle)
+- Removed `AuthResult` class from authentication system
+- Removed `ConcurrentCacheStore` example class for an ActiveSupport::Cache::MemoryStore-compatible interface with Rack::Attack
+- Removed OpenStruct dependency across the framework
+
+Documentation
+-------------
+
+- Updated migration guide with comprehensive examples for the new context object and step-by-step conversion instructions
+- Updated Logic class examples in advanced_routes and authentication_strategies to demonstrate new pattern
+- Enhanced documentation with API reference and helper method examples for the new context object
+
+AI Assistance
+-------------
+
+- AI-assisted architectural design for RequestContext Data class and security module reorganization
+- Comprehensive migration of Logic classes and documentation with AI guidance for consistency
+- Automated test validation and intelligent file organization following Ruby conventions
+
 .. _changelog-2.0.0-pre1:
 
 2.0.0-pre1 — 2025-09-10

data/Gemfile

@@ -25,7 +25,7 @@ end
 
 group :development do
   gem 'debug'
-  gem 'rubocop', require: false
+  gem 'rubocop', '~> 1.81.1', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    otto (2.0.0.pre.pre1)
+    otto (2.0.0.pre2)
       facets (~> 3.1)
+      logger (~> 1, < 2.0)
       loofah (~> 2.20)
       rack (~> 3.1, < 4.0)
       rack-parser (~> 0.7)
@@ -28,7 +29,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.13.2)
+    json (2.15.1)
     json_schemer (2.4.0)
       bigdecimal
       hana (~> 1.3)
@@ -41,21 +42,21 @@ GEM
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
     minitest (5.25.5)
-    nokogiri (1.18.9-aarch64-linux-gnu)
+    nokogiri (1.18.10-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.9-aarch64-linux-musl)
+    nokogiri (1.18.10-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.9-arm-linux-gnu)
+    nokogiri (1.18.10-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.9-arm-linux-musl)
+    nokogiri (1.18.10-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.18.9-arm64-darwin)
+    nokogiri (1.18.10-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.9-x86_64-darwin)
+    nokogiri (1.18.10-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.9-x86_64-linux-gnu)
+    nokogiri (1.18.10-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.18.9-x86_64-linux-musl)
+    nokogiri (1.18.10-x86_64-linux-musl)
       racc (~> 1.4)
     parallel (1.27.0)
     parser (3.3.9.0)
@@ -67,12 +68,12 @@ GEM
       prettyprint
     prettier_print (1.2.1)
     prettyprint (0.2.0)
-    prism (1.4.0)
+    prism (1.5.2)
     psych (5.2.6)
       date
       stringio
     racc (1.8.1)
-    rack (3.2.1)
+    rack (3.2.2)
     rack-attack (6.7.0)
       rack (>= 1.0, < 4)
     rack-parser (0.7.0)
@@ -87,10 +88,10 @@ GEM
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
-    regexp_parser (2.11.2)
+    regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
-    rexml (3.4.3)
+    rexml (3.4.4)
     rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -104,7 +105,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.5)
-    rubocop (1.80.2)
+    rubocop (1.81.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -112,10 +113,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.46.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.26.0)
@@ -173,7 +174,7 @@ DEPENDENCIES
   rack-test
   rackup
   rspec (~> 3.13)
-  rubocop
+  rubocop (~> 1.81.1)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/docs/.gitignore

@@ -1,3 +1,4 @@
 *
 !.gitignore
 !migrating/
+!migrating/*.md

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

@@ -0,0 +1,345 @@
+# 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
+
+# Or for middleware - FailureResult indicates failure
+if strategy_result.is_a?(Otto::Security::Authentication::FailureResult)
+  # handle failure
+else
+  # 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
+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.client_ipaddress }
+    )
+  end
+end
+```
+
+**Correct approach:**
+```ruby
+# GOOD - Use middleware-provided result
+class Controller::Base
+  def strategy_result
+    req.env['otto.strategy_result']  # Created by AuthenticationMiddleware
+  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)
+expect(result).to be_a(Otto::Security::Authentication::FailureResult)
+```
+
+## Architecture Clarifications
+
+### When StrategyResult is Created
+
+1. **Routes WITH `auth=...` requirement:**
+   - Strategy executes
+   - Returns `StrategyResult` (success) or `FailureResult` (failure)
+   - Middleware converts `FailureResult` to anonymous `StrategyResult` + 401 response
+
+2. **Routes WITHOUT `auth=...` requirement:**
+   - Middleware creates anonymous `StrategyResult`
+   - Sets `auth_method: 'anonymous'`
+
+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 AuthenticationMiddleware
+- **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/authentication_middleware.rb` - Auth middleware
+- `lib/otto/env_keys.rb` - Complete env key registry
+
+The documentation includes detailed usage patterns, session contracts, and examples for common scenarios.

data/lib/otto/core/configuration.rb

@@ -143,12 +143,12 @@ class Otto
       # @param default_strategy [String] Default strategy to use when none specified
       # @example
       #   otto.configure_auth_strategies({
-      #     'publicly' => Otto::Security::Authentication::Strategies::PublicStrategy.new,
+      #     'noauth' => Otto::Security::Authentication::Strategies::NoAuthStrategy.new,
       #     'authenticated' => Otto::Security::Authentication::Strategies::SessionStrategy.new(session_key: 'user_id'),
       #     'role:admin' => Otto::Security::Authentication::Strategies::RoleStrategy.new(['admin']),
       #     'api_key' => Otto::Security::Authentication::Strategies::APIKeyStrategy.new(api_keys: ['secret123'])
       #   })
-      def configure_auth_strategies(strategies, default_strategy: 'publicly')
+      def configure_auth_strategies(strategies, default_strategy: 'noauth')
         # Update existing @auth_config rather than creating a new one
         @auth_config[:auth_strategies] = strategies
         @auth_config[:default_auth_strategy] = default_strategy