otto 2.9.0 → 2.10.0

data/lib/otto/optional_dependency.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+
+class Otto
+  # Raised when an explicitly enabled feature cannot load its optional gem.
+  class OptionalDependencyError < ArgumentError; end
+
+  # Loads optional gems against the compatibility ranges Otto supports.
+  module OptionalDependency
+    module_function
+
+    def require!(gem_name, requirement, require_path:, feature:, alternative: nil)
+      version_requirement = Gem::Requirement.new(requirement)
+      guidance = "Add `gem '#{gem_name}', '#{requirement}'` to your Gemfile."
+      guidance = "#{guidance} #{alternative}" if alternative
+      installed_specs = Gem::Specification.find_all_by_name(gem_name)
+      active_spec = Gem.loaded_specs[gem_name]
+      compatible_spec = if active_spec && version_requirement.satisfied_by?(active_spec.version)
+                          active_spec
+                        else
+                          installed_specs
+                            .select { |spec| version_requirement.satisfied_by?(spec.version) }
+                            .max_by(&:version)
+                        end
+
+      unless compatible_spec
+        installed = installed_specs.map(&:version).sort.join(', ')
+        reason = installed.empty? ? 'it is not installed' : "installed version(s) #{installed} are incompatible"
+        raise OptionalDependencyError,
+              "#{feature} requires optional dependency '#{gem_name}' (#{version_requirement}), but #{reason}. #{guidance}"
+      end
+
+      load_error = begin
+        compatible_spec.activate
+        require require_path
+        nil
+      # Convert loader failures into a feature-specific configuration error.
+      # Gem::LoadError (activation conflicts) is a LoadError subclass, so one
+      # rescue covers both activation and require failures.
+      rescue LoadError => e
+        e
+      end
+
+      raise_load_error!(feature, gem_name, version_requirement, guidance, load_error) if load_error
+
+      compatible_spec
+    end
+
+    def raise_load_error!(feature, gem_name, requirement, guidance, error)
+      raise OptionalDependencyError,
+            "#{feature} requires optional dependency '#{gem_name}' (#{requirement}), but it could not be " \
+            "loaded: #{error.message}. #{guidance}",
+            cause: error
+    end
+  end
+end

data/lib/otto/privacy/config.rb

@@ -9,6 +9,7 @@ require 'digest'
 require 'concurrent'
 
 require_relative '../core/freezable'
+require_relative '../optional_dependency'
 
 class Otto
   module Privacy
@@ -31,6 +32,8 @@ class Otto
     class Config
       include Otto::Core::Freezable
 
+      MAXMIND_DB_REQUIREMENT = '~> 1.2'
+
       # Named privacy profiles: validated presets over the individual knobs,
       # so a deployment's observability posture is declared in one reviewable
       # word instead of inferred from knob combinations.
@@ -540,14 +543,13 @@ class Otto
       def build_maxmind_reader(path, option_name: 'geo_db_path')
         raise ArgumentError, "#{option_name} is not readable: #{path.inspect}" unless File.readable?(path)
 
-        begin
-          require 'maxmind/db'
-        rescue LoadError
-          raise ArgumentError,
-                "#{option_name} is set (#{path.inspect}) but the 'maxmind-db' gem is not available. " \
-                "Add `gem 'maxmind-db'` to your Gemfile, or inject your own reader via " \
-                "configure_ip_privacy(#{option_name.sub('_path', '_reader')}: ...)."
-        end
+        Otto::OptionalDependency.require!(
+          'maxmind-db',
+          MAXMIND_DB_REQUIREMENT,
+          require_path: 'maxmind/db',
+          feature: "#{option_name} database loading",
+          alternative: "Or inject a reader with `#{option_name.sub('_path', '_reader')}:`."
+        )
 
         begin
           MaxMind::DB.new(path, mode: MaxMind::DB::MODE_MEMORY)

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

@@ -73,20 +73,37 @@ class Otto
           #
           # Supports multiple role sources in order of precedence:
           # 1. result.user_roles (Array)
-          # 2. result.user[:roles] (Array)
-          # 3. result.user['roles'] (Array)
+          # 2. result.user[:roles] / result.user['roles'] (Hash user)
+          # 3. result.user.roles, then result.user.role (object-backed user:
+          #    ORM model, PORO, Data/Struct); #roles must return role names
           # 4. result.metadata[:user_roles] (Array)
           #
+          # A user object that is neither a Hash nor responds to `#roles`/`#role`
+          # contributes no roles rather than raising, so authorization yields a
+          # deny result instead of a NoMethodError.
+          #
           # @param result [StrategyResult] Authentication result
           # @return [Array<String>] Array of role strings
           def extract_roles(result)
             # Try direct user_roles accessor (e.g., from RoleStrategy)
             return Array(result.user_roles) if result.respond_to?(:user_roles) && result.user_roles
 
-            # Try user hash/object with roles
-            if result.user
-              roles = result.user[:roles] || result.user['roles']
+            # Hash access first (unchanged behaviour), then object-backed users
+            user = result.user
+            if user.is_a?(Hash)
+              roles = user[:roles] || user['roles']
               return Array(roles) if roles
+            else
+              # Same fallback as StrategyResult#roles: an empty or nil #roles
+              # falls through to a singular #role.
+              if user.respond_to?(:roles)
+                roles = Array(user.roles).map(&:to_s)
+                return roles unless roles.empty?
+              end
+              if user.respond_to?(:role)
+                role = user.role
+                return [role.to_s] if role
+              end
             end
 
             # Try metadata

data/lib/otto/security/authentication/strategies/api_key_strategy.rb

@@ -3,50 +3,213 @@
 # frozen_string_literal: true
 
 require_relative '../auth_strategy'
+require 'digest'
 require 'rack/utils'
 
 class Otto
   module Security
     module Authentication
       module Strategies
-        # API key authentication strategy
+        # API key authentication strategy.
+        #
+        # Accepts exactly one key source: a static list (`api_keys:`), a
+        # callable (`resolver:`), or a block. A resolver receives the presented
+        # key (a non-empty String, never env) and returns the account behind it,
+        # or nil/false when the key is unknown. Any other return value, including
+        # an empty container, counts as a match: an ORM relation from `where`,
+        # an empty Array from `select`, or `{}` from a cache miss is truthy and
+        # authenticates the caller. Return exactly one record (`find_by`,
+        # `first`) or nil. The strategy never branches on mode: a static list is
+        # wrapped in a resolver internally.
+        #
+        # Fails closed: a strategy with no source, or a static list with no
+        # non-empty key, is a misconfiguration and raises ArgumentError at
+        # construction rather than authenticating every caller. Only a truthy
+        # resolver return (for a static list: a constant-time match) grants
+        # success.
+        #
+        # A credential that was presented and rejected, including a non-String
+        # credential such as an array query parameter, fails TERMINALLY, so a bad
+        # key halts the strategy chain instead of falling through to a later
+        # anonymous-capable strategy. A missing credential fails non-terminally.
+        # Blank and non-String credentials are rejected before the resolver runs.
+        #
+        # Exceptions raised by a resolver propagate. A database outage must
+        # surface as an error, not as a silent 401 and never as success.
+        #
+        # Timing: the static list is compared in constant time against every
+        # configured key. Both sides are reduced to fixed-width SHA-256 digests
+        # first, so the comparison never short-circuits on a length mismatch and
+        # the lengths of configured keys are not observable. A black-box lookup
+        # cannot be made constant-time by the strategy; the documented pattern
+        # is to store SHA-256 digests and look up by {APIKeyStrategy.digest},
+        # which is constant-time by construction and keeps raw keys out of the
+        # database.
+        #
+        # The strategy never places the raw key in the result itself: the only
+        # strategy-generated field derived from the key is a short SHA-256
+        # fingerprint. With a resolver, `user` is whatever the resolver returns,
+        # verbatim; the result is stored in env['otto.strategy_result'] and
+        # exposed to handlers, so anything the application serializes or logs
+        # from it carries `user`. It is the resolver's responsibility not to
+        # return an object that holds the raw key: return the account, not the
+        # ApiKey row that stores the key, and store digests. A resolver that
+        # returns the presented key String itself as the user raises
+        # ArgumentError.
+        #
+        # The query/form parameter path is opt-in (`param_name:`), because keys in
+        # URLs are recorded by access logs, proxies, and browser history.
+        #
+        # Scope: this is a small static-allowlist authenticator shipped as a
+        # low-dependency convenience and reference implementation. It has no
+        # native support for runtime addition or revocation, expiration, roles
+        # or scopes, key metadata, quotas, a management API, audit history, or
+        # hashed verifier storage. The resolver form delegates those concerns
+        # to the application's key store; see docs/guides/authentication.md.
+        #
+        # @example Static list, header only (recommended)
+        #   APIKeyStrategy.new(api_keys: ['secret123'])
+        # @example Block resolver looking up a stored digest
+        #   APIKeyStrategy.new do |presented_key|
+        #     ApiKey.find_by(digest: APIKeyStrategy.digest(presented_key))&.account
+        #   end
+        # @example Callable resolver (anything responding to #call)
+        #   APIKeyStrategy.new(resolver: repo.method(:find_by_key))
+        # @example Also accept ?api_key= (logged in URLs; prefer the header)
+        #   APIKeyStrategy.new(api_keys: ['secret123'], param_name: 'api_key')
         class APIKeyStrategy < AuthStrategy
-          def initialize(api_keys: [], header_name: 'X-API-Key', param_name: 'api_key')
-            @api_keys = Array(api_keys)
+          # Full SHA-256 hex digest of a key. Store this instead of the raw key
+          # and look up presented keys by their digest.
+          #
+          # @param key [String]
+          # @return [String] 64-char hex digest
+          def self.digest(key)
+            Digest::SHA256.hexdigest(key)
+          end
+
+          # @param api_keys [String, Array<String>, nil] static list of valid API keys
+          # @param resolver [#call, nil] callable receiving the presented key and
+          #   returning the account (truthy) or nil/false when unknown
+          # @param header_name [String] request header carrying the key
+          # @param param_name [String, nil] query/form parameter carrying the key.
+          #   Defaults to nil (header only): keys placed in a URL are captured by
+          #   access logs, proxies, and browser history. Pass 'api_key' to opt in.
+          # @yieldparam presented_key [String] the non-empty presented key
+          # @yieldreturn [Object, nil, false] the account behind the key, or
+          #   nil/false when the key is unknown
+          # @raise [ArgumentError] if no source, or more than one, is given
+          # @raise [ArgumentError] if resolver: does not respond to #call
+          # @raise [ArgumentError] if api_keys: contains no non-empty API key
+          def initialize(api_keys: nil, resolver: nil, header_name: 'X-API-Key', param_name: nil, &block)
+            super()
+            @resolver = build_resolver(api_keys, resolver, block)
             @header_name = header_name
             @param_name = param_name
           end
 
           def authenticate(env, _requirement)
-            # Try header first, then query parameter
+            # Header first; the parameter path is consulted only when opted in.
             api_key = env["HTTP_#{@header_name.upcase.tr('-', '_')}"]
 
-            if api_key.nil?
+            if api_key.nil? && @param_name
               request = Otto::Request.new(env)
               api_key = request.params[@param_name]
             end
 
-            return failure('No API key provided') unless api_key
+            # '' is truthy in Ruby; treat it, and a whitespace-only value, as a
+            # missing credential. The static list already refuses blank keys, so
+            # the resolver must never be asked about one either.
+            return failure('No API key provided') if api_key.nil? || (api_key.is_a?(String) && api_key.strip.empty?)
+
+            # A non-String credential (e.g. `?api_key[]=k` yields an Array) was
+            # still presented, so reject it terminally rather than handing it to
+            # the resolver. Credentials were explicitly presented and rejected:
+            # fail closed.
+            return failure('Invalid API key', terminal: true) unless api_key.is_a?(String)
 
-            if @api_keys.empty? || valid_api_key?(api_key)
-              # Create a simple user hash for API key authentication
-              user_data = { api_key: api_key }
-              success(user: user_data, api_key: api_key)
-            else
-              failure('Invalid API key')
+            # Resolver exceptions propagate deliberately (see class docs).
+            user = @resolver.call(api_key)
+            return failure('Invalid API key', terminal: true) unless user
+
+            # The most likely naive misuse: `->(k) { k if keys.include?(k) }`.
+            # Fail loud before the key can reach the result and env.
+            if user.is_a?(String) && constant_time_equal?(user, api_key)
+              raise ArgumentError,
+                    'APIKeyStrategy resolver returned the presented key as the user; ' \
+                    'return the account behind the key, not the key'
             end
+
+            # Identify the credential by a non-reversible fingerprint. The strategy
+            # itself never places the raw key in the result; `user` is the
+            # resolver's return value, verbatim (see class docs).
+            success(user: user,
+                    auth_method: 'api_key',
+                    api_key_fingerprint: key_fingerprint(api_key))
           end
 
           private
 
-          # Constant-time membership check over the configured API keys. Compares
-          # against every key without short-circuiting so match position/membership is
-          # not leaked via timing.
-          def valid_api_key?(api_key)
-            @api_keys.reduce(false) do |matched, key|
-              Rack::Utils.secure_compare(key, api_key) || matched
+          def build_resolver(api_keys, resolver, block)
+            sources = [api_keys, resolver, block].count { |source| !source.nil? }
+            if sources > 1
+              raise ArgumentError,
+                    'APIKeyStrategy: pass api_keys:, resolver:, or a block, not more than one'
+            end
+            # `api_keys: nil` and omitting every source are indistinguishable
+            # here, so one message covers both.
+            if sources.zero?
+              raise ArgumentError,
+                    'APIKeyStrategy requires a key source: at least one non-empty API key ' \
+                    '(api_keys:), a resolver:, or a block'
+            end
+
+            return static_resolver(api_keys) unless api_keys.nil?
+            return block if block
+
+            raise ArgumentError, 'APIKeyStrategy resolver: must respond to #call' unless resolver.respond_to?(:call)
+
+            resolver
+          end
+
+          # Wrap a static key list in a resolver performing a constant-time,
+          # non-short-circuiting membership check.
+          def static_resolver(api_keys)
+            # `to_s` returns the caller's String and the strategy only ever
+            # receives a shallow freeze from config finalization, so the digest
+            # is taken now: a caller mutating its key after boot cannot change
+            # which credential is accepted, and the raw keys are not retained.
+            # Keys are matched verbatim, but a whitespace-only value is a blank
+            # configuration (`API_KEYS=" "`), not a credential: reject it so the
+            # fail-closed startup guarantee covers it.
+            digests = Array(api_keys).map(&:to_s).reject { |key| key.strip.empty? }
+                                     .map { |key| self.class.digest(key).freeze }.freeze
+            if digests.empty?
+              raise ArgumentError,
+                    'APIKeyStrategy requires at least one non-empty API key ' \
+                    '(api_keys: was empty or contained only blank values)'
+            end
+
+            lambda do |presented|
+              presented_digest = self.class.digest(presented)
+              matched = digests.reduce(false) do |acc, digest|
+                Rack::Utils.secure_compare(digest, presented_digest) || acc
+              end
+              matched ? { api_key_fingerprint: presented_digest[0, 12] } : nil
             end
           end
+
+          # Constant-time equality that does not leak the length of either side:
+          # `Rack::Utils.secure_compare` returns immediately on a length mismatch,
+          # so compare fixed-width digests instead of the raw values.
+          def constant_time_equal?(left, right)
+            Rack::Utils.secure_compare(self.class.digest(left), self.class.digest(right))
+          end
+
+          # Short, non-reversible identifier for a key: enough to correlate
+          # requests and audit logs without exposing the credential.
+          def key_fingerprint(api_key)
+            self.class.digest(api_key)[0, 12]
+          end
         end
       end
     end

data/lib/otto/security/authentication/strategies/permission_strategy.rb

@@ -11,6 +11,7 @@ class Otto
         # Permission-based authentication strategy
         class PermissionStrategy < AuthStrategy
           def initialize(required_permissions, session_key: 'user_permissions')
+            super()
             @required_permissions = Array(required_permissions)
             @session_key = session_key
           end

data/lib/otto/security/authentication/strategies/role_strategy.rb

@@ -11,6 +11,7 @@ class Otto
         # Role-based authentication strategy
         class RoleStrategy < AuthStrategy
           def initialize(allowed_roles, session_key: 'user_roles')
+            super()
             @allowed_roles = Array(allowed_roles)
             @session_key = session_key
           end

data/lib/otto/security/authentication/strategies/session_strategy.rb

@@ -11,6 +11,7 @@ class Otto
         # Session-based authentication strategy
         class SessionStrategy < AuthStrategy
           def initialize(session_key: 'user_id', session_store: nil)
+            super()
             @session_key = session_key
             @session_store = session_store
           end

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

@@ -159,45 +159,34 @@ class Otto
 
         # Check if the user has a specific role
         #
+        # A user model that defines `#has_role?` is asked directly. Otherwise
+        # the answer is derived from {#roles}, so the predicate and the accessor
+        # always agree: `has_role?(r)` is `roles.include?(r.to_s)` for Hash,
+        # PORO, ORM, Set-backed, and single-`#role` users alike.
+        #
         # @param role [String, Symbol] Role to check
         # @return [Boolean] True if user has the role
         def has_role?(role)
           return false unless authenticated?
+          return user.has_role?(role) if user.respond_to?(:has_role?)
 
-          # Try user model methods first, fall back to hash access for backward compatibility
-          if user.respond_to?(:role)
-            user.role.to_s == role.to_s
-          elsif user.respond_to?(:has_role?)
-            user.has_role?(role)
-          elsif user.is_a?(Hash)
-            user_role = user[:role] || user['role']
-            user_role.to_s == role.to_s
-          else
-            false
-          end
+          roles.include?(role.to_s)
         end
 
         # Check if the user has a specific permission
         #
+        # A user model that defines `#has_permission?` is asked directly.
+        # Otherwise the answer is derived from {#permissions}, so the predicate
+        # and the accessor always agree, including for Set-backed and other
+        # non-Array Enumerable collections.
+        #
         # @param permission [String, Symbol] Permission to check
         # @return [Boolean] True if user has the permission
         def has_permission?(permission)
           return false unless authenticated?
+          return user.has_permission?(permission) if user.respond_to?(:has_permission?)
 
-          # Try user model methods first, fall back to hash access for backward compatibility
-          if user.respond_to?(:has_permission?)
-            user.has_permission?(permission)
-          elsif user.respond_to?(:permissions)
-            permissions = user.permissions || []
-            permissions = [permissions] unless permissions.is_a?(Array)
-            permissions.map(&:to_s).include?(permission.to_s)
-          elsif user.is_a?(Hash)
-            permissions = user[:permissions] || user['permissions'] || []
-            permissions = [permissions] unless permissions.is_a?(Array)
-            permissions.map(&:to_s).include?(permission.to_s)
-          else
-            false
-          end
+          permissions.include?(permission.to_s)
         end
 
         # Check if the user has any of the specified roles
@@ -257,10 +246,31 @@ class Otto
 
         # Get all user roles as an array
         #
+        # Supports object-backed users (ORM models, POROs, Data/Struct) via
+        # `#roles` / `#role`, and Hash users via `:roles`/`'roles'` then
+        # `:role`/`'role'`. Never calls `#[]` on a non-Hash user, so a model
+        # without role support yields `[]` instead of raising. `#roles` on an
+        # object must return role names (Strings or Symbols, in any Enumerable);
+        # an association of role records is stringified as-is and matches
+        # nothing, which denies rather than grants.
+        #
         # @return [Array<String>] Array of roles (empty if none)
         def roles
           return [] unless authenticated?
 
+          # Try user model methods first, fall back to hash access for backward compatibility
+          if user.respond_to?(:roles)
+            normalized = normalize_list(user.roles)
+            return normalized unless normalized.empty?
+          end
+
+          if user.respond_to?(:role)
+            role = user.role
+            return [role.to_s] if role
+          end
+
+          return [] unless user.is_a?(Hash)
+
           roles_data = user[:roles] || user['roles']
           if roles_data.is_a?(Array)
             roles_data.map(&:to_s)
@@ -274,13 +284,21 @@ class Otto
 
         # Get all user permissions as an array
         #
+        # Supports object-backed users via `#permissions` and Hash users via
+        # `:permissions`/`'permissions'`. Never calls `#[]` on a non-Hash user.
+        #
         # @return [Array<String>] Array of permissions (empty if none)
         def permissions
           return [] unless authenticated?
 
-          perms = user[:permissions] || user['permissions'] || []
-          perms = [perms] unless perms.is_a?(Array)
-          perms.map(&:to_s)
+          # Try user model methods first, fall back to hash access for backward compatibility
+          if user.respond_to?(:permissions)
+            normalize_list(user.permissions)
+          elsif user.is_a?(Hash)
+            normalize_list(user[:permissions] || user['permissions'])
+          else
+            []
+          end
         end
 
         # Create a string representation for debugging
@@ -332,6 +350,18 @@ class Otto
                        permissions: permissions,
           }
         end
+
+        private
+
+        # Coerce a roles/permissions value into an Array of Strings. Enumerables
+        # (Array, Set, an ORM relation) expand to their elements; a scalar
+        # becomes a one-element list; nil becomes [].
+        #
+        # @param value [Array, Enumerable, Object, nil]
+        # @return [Array<String>]
+        def normalize_list(value)
+          Array(value).map(&:to_s)
+        end
       end
     end
   end