otto 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4e62574b6cb588f8dd99890758af5689dc23732d7a920c0023627a128a5ab5a
-  data.tar.gz: 658e3f7cf3feedf1ee8a120bcb4a5121d2b70c0d5f584b96115ded86d6d2132c
+  metadata.gz: 0616e034fc5859c42ed2eb48e1d123abdd1b36bca93422cf858d51331843c2c9
+  data.tar.gz: 667c3067cdd71ed41ef733c479798836522c32d37044edeb5f78d33c04b14818
 SHA512:
-  metadata.gz: f4426d3362c6f2ceb81ca1d8c1dfd55dad7b404218b6a3715394bec29e466b6bf0f09d290bb11fa157eaaa6c2889e702ccac97ba4f5496e947005cc083046332
-  data.tar.gz: dca5f99161a47a01514f58a7959062d215b5371f2e8165f57399f77cece4529f57ae4e0cb83224fe5fd93acdd4575dc1b04bbb9682afa82f2ad4e98258b9786d
+  metadata.gz: c219d4864ffc3090983ee50828279914dc052d0d65f5fd75dbaff812a1fee5d32880c325956d778c9a68e39e396e0f855f271eb3355ddee9d846e186586c57a2
+  data.tar.gz: d32b8d2235fe0d2c95510c4ec5f1623f30a6039bac1a309878af03907458fd9a51ea18f6e5584dfe88754a45cef25469f52ba72bee7847e97b87f2e481672e9d

data/.github/workflows/release-gem.yml

@@ -132,7 +132,11 @@ jobs:
         uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
         with:
           bundler-cache: true
-          ruby-version: ruby   # latest stable Ruby installed by setup-ruby
+          # Pinned to 3.3 (oldest non-experimental Ruby in the CI matrix).
+          # Latest stable (4.0) ships ipaddr 1.2.8 as a default gem, which
+          # bundler 2.7.x cannot override with the lockfile's 1.2.9 - the
+          # same reason Ruby 4.0 is `experimental: true` in ci.yml.
+          ruby-version: "3.3"
 
       - name: Verify release tag matches Otto::VERSION
         env:

data/{CLAUDE.md → AGENTS.md}

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides essential guidance to Claude Code when working with Otto.
+This file provides essential guidance to AI agents when working with Otto.
 
 ## Error Handler Registration
 

data/CHANGELOG.rst

@@ -7,6 +7,18 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.2.0:
+
+2.2.0 — 2026-06-09
+==================
+
+Added
+-----
+
+- Added ``AuthorizationFailure`` result type for auth strategies to signal 403 Forbidden distinct from 401 Unauthorized. Strategies that perform combined authentication and authorization in one pass can now return ``authorization_failure(reason)`` when a valid credential is denied a permission, allowing ``RouteAuthWrapper`` to map the result to a proper 403 response rather than collapsing it to 401.
+- Added ``#authorization_failure`` helper to ``AuthStrategy`` base class for consistent error signaling across strategy implementations.
+- Extracted ``#strategy_auth_method`` private helper to handle anonymous strategy classes (common in tests) that have a nil ``#name``.
+
 .. _changelog-2.1.0:
 
 2.1.0 — 2026-05-27

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.1.0)
+    otto (2.2.0)
       concurrent-ruby (~> 1.3, < 2.0)
       ipaddr (~> 1, < 2.0)
       logger (~> 1, < 2.0)

data/lib/otto/security/authentication/auth_strategy.rb

@@ -31,20 +31,47 @@ class Otto
           Otto::Security::Authentication::StrategyResult.new(
             session: session,
             user: user,
-            auth_method: auth_method || self.class.name.split('::').last,
+            auth_method: auth_method || strategy_auth_method,
             metadata: metadata,
             strategy_name: nil # Will be set by RouteAuthWrapper
           )
         end
 
         # Helper for authentication failure - return AuthFailure
+        #
+        # Use for a missing, invalid, or expired credential. RouteAuthWrapper maps
+        # this to 401 Unauthorized. For a VALID credential that is not permitted,
+        # use #authorization_failure instead (403 Forbidden).
         def failure(reason = nil)
           Otto.logger.debug "[#{self.class}] Authentication failed: #{reason}" if reason
           Otto::Security::Authentication::AuthFailure.new(
             failure_reason: reason || 'Authentication failed',
-            auth_method: self.class.name.split('::').last
+            auth_method: strategy_auth_method
+          )
+        end
+
+        # Helper for authorization failure - return AuthorizationFailure
+        #
+        # Use when the credential is valid but the authenticated subject is not
+        # permitted (wrong role, missing permission). RouteAuthWrapper maps this to
+        # 403 Forbidden, letting clients distinguish "authenticate again" (401) from
+        # "you lack this permission" (403). See AuthorizationFailure.
+        def authorization_failure(reason = nil)
+          Otto.logger.debug "[#{self.class}] Authorization denied: #{reason}" if reason
+          Otto::Security::Authentication::AuthorizationFailure.new(
+            failure_reason: reason || 'Authorization denied',
+            auth_method: strategy_auth_method
           )
         end
+
+        private
+
+        # Short auth_method label from the strategy class name. Anonymous strategy
+        # classes (Class.new(...), common in tests) have a nil #name, so fall back
+        # to a generic label rather than raising on nil#split.
+        def strategy_auth_method
+          (self.class.name || 'AuthStrategy').split('::').last
+        end
       end
     end
   end

data/lib/otto/security/authentication/authorization_failure.rb

@@ -0,0 +1,56 @@
+# lib/otto/security/authentication/authorization_failure.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Security
+    module Authentication
+      # Result for AUTHORIZATION failures (authenticated, but not permitted).
+      #
+      # This is distinct from AuthFailure, which represents an AUTHENTICATION
+      # failure (no/invalid/expired credential). A strategy that performs both
+      # authentication and authorization in one pass (e.g. a token strategy that
+      # also enforces a role/permission encoded in the route requirement) returns:
+      #
+      #   * AuthFailure          -> credential missing/invalid  -> 401 Unauthorized
+      #   * AuthorizationFailure -> credential valid, but denied -> 403 Forbidden
+      #
+      # Without this type a combined strategy could only return AuthFailure, and
+      # RouteAuthWrapper would collapse an authorization denial to 401 — leaving a
+      # client unable to distinguish "authenticate again" from "you lack this
+      # permission." The wrapper maps this type to ResponseBuilder#forbidden (403);
+      # see RouteAuthWrapper#handle_all_strategies_failed.
+      #
+      # NOTE: Otto's built-in Layer-1 role check (RoleAuthorization, driven by the
+      # `role=` route token) already yields 403 for role mismatches on a successful
+      # StrategyResult. This type covers the complementary case: a strategy that
+      # owns authorization itself (including permission tiers, which Layer-1 does
+      # not model) and needs to signal a 403 directly.
+      AuthorizationFailure = Data.define(:failure_reason, :auth_method) do
+        # Authorization failures are not an authenticated request state. The
+        # request never reaches the handler, so handler-facing predicates report
+        # the same "no user context" shape AuthFailure does.
+        #
+        # @return [Boolean] False
+        def authenticated?
+          false
+        end
+
+        # @return [Boolean] True (no user context attached to a denial)
+        def anonymous?
+          true
+        end
+
+        # @return [Hash] Empty hash
+        def user_context
+          {}
+        end
+
+        # @return [String] Debug representation
+        def inspect
+          "#<AuthorizationFailure reason=#{failure_reason.inspect} method=#{auth_method}>"
+        end
+      end
+    end
+  end
+end

data/lib/otto/security/authentication/route_auth_wrapper.rb

@@ -106,11 +106,18 @@ class Otto
                                         duration, total_start_time, failed_strategies)
             end
 
-            # Handle authentication failure - continue to next strategy
-            next unless result.is_a?(AuthFailure)
+            # Handle a failure (authentication OR authorization) - record it and
+            # continue to the next strategy (OR logic; a later success still wins).
+            # AuthorizationFailure (valid credential, denied) is tagged so the
+            # final response is 403 instead of 401. See handle_all_strategies_failed.
+            next unless result.is_a?(AuthFailure) || result.is_a?(AuthorizationFailure)
 
             log_strategy_failure(env, strategy_name, result, duration, auth_requirements, requirement)
-            failed_strategies << { strategy: strategy_name, reason: result.failure_reason }
+            failed_strategies << {
+              strategy: strategy_name,
+              reason: result.failure_reason,
+              authorization: result.is_a?(AuthorizationFailure),
+            }
           end
 
           # All strategies failed
@@ -156,6 +163,14 @@ class Otto
             strategy_name: failure_strategy_name
           )
 
+          # Authorization denial wins over authentication failure: if any strategy
+          # authenticated the subject but denied authorization (wrong role/missing
+          # permission), respond 403 Forbidden rather than 401 — the subject IS
+          # authenticated, they simply lack access. A bare 401 would (incorrectly)
+          # tell a logged-in client to re-authenticate.
+          authz_denial = failed_strategies.find { |f| f[:authorization] }
+          return @response_builder.forbidden(env, authz_denial[:reason]) if authz_denial
+
           last_failure = if failed_strategies.any?
                            AuthFailure.new(
                              failure_reason: failed_strategies.last[:reason],

data/lib/otto/security/authentication.rb

@@ -8,6 +8,7 @@
 require_relative 'authentication/auth_strategy'
 require_relative 'authentication/strategy_result'
 require_relative 'authentication/auth_failure'
+require_relative 'authentication/authorization_failure'
 require_relative 'authentication/route_auth_wrapper'
 
 # Load all strategies
@@ -31,4 +32,5 @@ class Otto
   # Top-level backward compatibility aliases
   StrategyResult = Security::Authentication::StrategyResult
   AuthFailure = Security::Authentication::AuthFailure
+  AuthorizationFailure = Security::Authentication::AuthorizationFailure
 end

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -149,8 +149,8 @@ files:
 - ".reek.yml"
 - ".rspec"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.rst
-- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -281,6 +281,7 @@ files:
 - lib/otto/security/authentication.rb
 - lib/otto/security/authentication/auth_failure.rb
 - lib/otto/security/authentication/auth_strategy.rb
+- lib/otto/security/authentication/authorization_failure.rb
 - lib/otto/security/authentication/route_auth_wrapper.rb
 - lib/otto/security/authentication/route_auth_wrapper/response_builder.rb
 - lib/otto/security/authentication/route_auth_wrapper/role_authorization.rb