otto 2.9.0 → 2.11.0

data/lib/otto/mcp/server.rb

@@ -8,6 +8,7 @@ require_relative 'route_parser'
 require_relative 'auth/token'
 require_relative 'schema_validation'
 require_relative 'rate_limiting'
+require_relative 'options'
 require_relative '../security/constant_resolver'
 
 class Otto
@@ -16,18 +17,67 @@ class Otto
     class Server
       attr_reader :protocol, :otto_instance
 
+      # Normalize raw options into the canonical MCP option hash.
+      #
+      # @param opts [Hash] raw options
+      # @param scope [Symbol] :explicit (strict, for #enable_mcp!) or
+      #   :constructor (ignores non-MCP keys, for Otto.new)
+      # @see Otto::MCP::Options.normalize
+      def self.normalize_options(opts = {}, scope = :explicit)
+        Otto::MCP::Options.normalize(opts, scope)
+      end
+
       def initialize(otto_instance)
         @otto_instance = otto_instance
         @protocol      = Protocol.new(otto_instance)
         @enabled       = false
       end
 
+      # Warning emitted when the MCP HTTP endpoint is exposed with no token
+      # authentication. Unconditional (not gated on Otto.debug): an
+      # unauthenticated MCP endpoint lets any caller invoke every registered
+      # tool, so it must be visible in normal boot output.
+      UNAUTHENTICATED_WARNING = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        [MCP] HTTP endpoint %s is enabled without authentication:
+        any caller can list and invoke MCP tools and resources.
+        Pass auth_tokens: ['<token>'] to require a bearer token, or
+        allow_unauthenticated: true to acknowledge this intentionally.
+      MSG
+
+      # Enable the MCP server.
+      #
+      # Enabling is one-shot. Each call appends a route, an endpoint-setting
+      # proc and the MCP middleware to the Otto instance without removing the
+      # previous set, so a second call with a different endpoint would leave
+      # the first endpoint routed but guarded by nothing (the auth middleware
+      # only matches the newest endpoint). Rather than try to unwind that,
+      # a second call raises.
+      #
+      # @param options [Hash] canonical or aliased options; normalized via
+      #   {.normalize_options}, so both the canonical keys (:http_endpoint,
+      #   :auth_tokens, ...) and their mcp_-prefixed spellings
+      #   (:mcp_endpoint, :mcp_auth_tokens, ...) are accepted.
+      # @raise [ArgumentError] if the server is already enabled
       def enable!(options = {})
-        @enabled              = true
-        @http_endpoint        = options.fetch(:http_endpoint, '/_mcp')
-        @auth_tokens          = options[:auth_tokens] || []
-        @enable_validation    = options.fetch(:enable_validation, true)
-        @enable_rate_limiting = options.fetch(:enable_rate_limiting, true)
+        if @enabled
+          raise ArgumentError,
+                "MCP server is already enabled on #{@http_endpoint}; pass all MCP options " \
+                'in a single Otto.new or enable_mcp! call'
+        end
+
+        options = self.class.normalize_options(options)
+
+        Validator.ensure_available! if options[:enable_validation]
+        Otto::Security::RateLimiting.ensure_available! if options[:enable_rate_limiting]
+
+        @enabled               = true
+        @http_endpoint         = options[:http_endpoint]
+        @auth_tokens           = options[:auth_tokens]
+        @enable_validation     = options[:enable_validation]
+        @enable_rate_limiting  = options[:enable_rate_limiting]
+        @allow_unauthenticated = options[:allow_unauthenticated]
+
+        apply_rate_limits(options)
 
         # Configure middleware
         configure_middleware(options)
@@ -35,6 +85,8 @@ class Otto
         # Add MCP endpoint route to Otto
         add_mcp_endpoint_route
 
+        warn_if_unauthenticated!
+
         Otto.logger.info "[MCP] Server enabled with HTTP endpoint: #{@http_endpoint}" if Otto.debug
       end
 
@@ -53,42 +105,82 @@ class Otto
 
       private
 
+      # Publish the per-minute limits under the keys RateLimitMiddleware /
+      # RateLimiter.configure_rack_attack! already read, via Otto's sanctioned
+      # rate-limiting configuration entry point. Before this, the values passed
+      # to enable! were dead and the hardcoded 60/20 always won.
+      #
+      # The endpoint travels with them. Rack::Attack is mounted by the host app
+      # OUTSIDE Otto and runs before any of Otto's middleware, so the
+      # env['otto.mcp_http_endpoint'] set by add_mcp_endpoint_route is not yet
+      # present when the throttles are evaluated; without this, a custom
+      # endpoint was compared against the '/_mcp' fallback and never throttled.
+      def apply_rate_limits(options)
+        return unless @enable_rate_limiting
+
+        @otto_instance.configure_rate_limiting(
+          mcp_http_endpoint: @http_endpoint,
+          mcp_requests_per_minute: options[:requests_per_minute],
+          tool_calls_per_minute: options[:tools_per_minute]
+        )
+      end
+
+      def warn_if_unauthenticated!
+        return if @auth_tokens.any? || @allow_unauthenticated
+
+        Otto.logger.warn format(UNAUTHENTICATED_WARNING, @http_endpoint)
+      end
+
       def configure_middleware(_options)
-        # Configure middleware in security-optimal order using explicit positioning:
-        # 1. Rate limiting (reject excessive requests early) - position: :first
-        # 2. Authentication (validate credentials before parsing) - default append
-        # 3. Validation (expensive JSON schema validation last) - position: :last
+        # Target EXECUTION order (outermost first, i.e. what a request meets in
+        # turn), security-optimal:
+        #   1. Rate limiting  — shed excessive load before spending any work
+        #   2. Authentication — reject anonymous callers before parsing bodies
+        #   3. Validation     — expensive JSON schema check only on requests
+        #                       that already proved themselves
+        #
+        # MiddlewareStack stores entries in the REVERSE of execution order
+        # (#wrap folds with reduce, so a later array entry is a further-out
+        # wrapper). Registration therefore runs innermost-first: validation is
+        # pinned :innermost, then auth is appended, then rate limiting. The
+        # previous code read the positions as execution order and produced the
+        # exact inverse — validation ran ahead of auth, so unauthenticated
+        # callers reached the schema validator.
 
         middleware = @otto_instance.instance_variable_get(:@middleware)
 
-        # Configure rate limiting first (explicit position for clarity)
-        if @enable_rate_limiting
+        # Innermost (last to execute): schema validation, closest to the app.
+        if @enable_validation
           middleware.add_with_position(
-            Otto::MCP::RateLimitMiddleware,
-            @otto_instance.security_config,
-            position: :first
+            Otto::MCP::SchemaValidationMiddleware,
+            position: :innermost
           )
-          Otto.logger.debug '[MCP] Rate limiting enabled (position: first)' if Otto.debug
+          Otto.logger.debug '[MCP] Schema validation enabled (executes last)' if Otto.debug
         end
 
-        # Configure authentication second (default append order)
+        # Middle: authentication, outside validation and inside rate limiting.
         if @auth_tokens.any?
           @auth = Otto::MCP::Auth::TokenAuth.new(@auth_tokens)
           @otto_instance.security_config.mcp_auth = @auth
-          @otto_instance.use Otto::MCP::Auth::TokenMiddleware
-          Otto.logger.debug '[MCP] Token authentication enabled' if Otto.debug
+          # Pass security_config explicitly: TokenMiddleware is not in
+          # MiddlewareStack#middleware_needs_config?, so #wrap would build it
+          # with a nil config and — now that the middleware fails closed —
+          # reject every request, valid token included.
+          @otto_instance.use Otto::MCP::Auth::TokenMiddleware, @otto_instance.security_config
+          Otto.logger.debug '[MCP] Token authentication enabled (executes after rate limiting)' if Otto.debug
         end
 
-        # Configure validation last (explicit position for clarity)
-        return unless @enable_validation
-
-        middleware.add_with_position(
-          Otto::MCP::SchemaValidationMiddleware,
-          position: :last
-        )
-        Otto.logger.debug '[MCP] Schema validation enabled (position: last)' if Otto.debug
+        # Outermost of the three (first to execute): rate limiting.
+        if @enable_rate_limiting
+          middleware.add_with_position(
+            Otto::MCP::RateLimitMiddleware,
+            @otto_instance.security_config,
+            position: :last
+          )
+          Otto.logger.debug '[MCP] Rate limiting enabled (executes first)' if Otto.debug
+        end
 
-        # Validate middleware order (should pass with explicit positioning)
+        # Validate execution order (should pass with the positioning above).
         warnings = middleware.validate_mcp_middleware_order
         warnings.each { |warning| Otto.logger.warn warning }
       end
@@ -102,13 +194,20 @@ class Otto
         @otto_instance.routes[:POST] ||= []
         @otto_instance.routes[:POST] << mcp_route
 
-        @otto_instance.routes_literal[:POST]               ||= {}
-        @otto_instance.routes_literal[:POST][@http_endpoint] = mcp_route
-
-        # Ensure env carries endpoint for middlewares
+        # Keyed by the normalized path, as the router keys every literal route
+        # and normalizes PATH_INFO before the lookup: a configured trailing
+        # slash ('/a/') or the root ('/') otherwise registers a key the lookup
+        # can never hit, while Otto::MCP.endpoint_path? still claims the path.
+        @otto_instance.routes_literal[:POST] ||= {}
+        @otto_instance.routes_literal[:POST][Otto::Utils.normalize_path(@http_endpoint)] = mcp_route
+
+        # Ensure env carries endpoint for middlewares. Close over a local copy:
+        # the proc must keep announcing the endpoint it was registered for even
+        # if the ivar is ever reassigned.
+        endpoint = @http_endpoint
         @otto_instance.use proc { |app|
           lambda { |env|
-            env['otto.mcp_http_endpoint'] = @http_endpoint
+            env['otto.mcp_http_endpoint'] = endpoint
             app.call(env)
           }
         }

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