vector_mcp 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de0f694bd85fb9d217c352fc907f7d77c27ee3837eea3512c8ca1791c53313c2
-  data.tar.gz: 86f0a7ab8c95e744ef8d80cb77faddaa195cef6636ea9fe175631b01bc0b0982
+  metadata.gz: 8125dfaaa8d0965448eac78401a013a1f5e41292f29141a72c44fca6dbb96cba
+  data.tar.gz: cef6523bbd0c43e969102f5776f6bcb5f2e6a9e10507b4faee1839258fe7f39f
 SHA512:
-  metadata.gz: c0f1f384fd9d654cc3385a87937c656dee9beaf38e0aeed6f0e92542366c17051615b774b58d1ecc2eb89dd23e6a6737e85e1dcdfb6d4c239a182d0d3c98f31f
-  data.tar.gz: 8d0047290e1033266498f197b94b3d51eb88b700c46e44f15229de985a74eb57889f8381887beb92b0007883244de8f0c53b652a9a8939963f30d3c81fecb406
+  metadata.gz: 6dafbddbeeb279f3232ad45c979b94b92266b1c05060f057dd747bc51ad6cc290da9c30886c9d72cee0445554445cf78e963efd354481974b7b875a5c98e0d21
+  data.tar.gz: 68003e44e084dc40cef4ae04add212901c65056d5432a18aad00550fc8055537812693b915b1f6b00c7e409178ea0801d54f3c9fc3a350c3cca5c65f9afcf700

data/CHANGELOG.md

@@ -1,4 +1,27 @@
-## [Unreleased]
+## [0.5.0] – 2026-04-22
+
+### Added
+
+* **Token-Based Field Anonymization**: Added a general-purpose anonymization pipeline that substitutes sensitive string fields with stable opaque tokens before tool results reach the LLM and restores them on inbound tool invocations.
+  - `VectorMCP::TokenStore` — thread-safe bidirectional value ↔ token store with idempotent tokenization.
+  - `VectorMCP::Util::TokenSweeper` — stateless recursive traversal utility for parsed JSON structures.
+  - `VectorMCP::Middleware::Anonymizer` — middleware wiring the store and sweeper with application-supplied field rules and optional atomic-key handling; registers via `anonymizer.install_on(server)`.
+
+* **OAuth 2.1 Resource Server mode (HTTP Stream transport)**: `enable_authentication!` now accepts a `resource_metadata_url:` option. When set, unauthenticated requests to `/mcp` return HTTP `401` with a `WWW-Authenticate: Bearer realm="mcp", resource_metadata="<url>"` header (RFC 9728), enabling MCP clients such as Claude Desktop to discover the authorization server and initiate OAuth 2.1 + PKCE flows. Opt-in: when `resource_metadata_url` is not set, the existing JSON-RPC `-32401` behavior is unchanged. See [docs/oauth_resource_server.md](docs/oauth_resource_server.md) and [docs/rails_oauth_integration.md](docs/rails_oauth_integration.md) for end-to-end guidance.
+
+### Changed
+
+* **Auth Result Value Object**: Replaced the internal authentication result hashes with a dedicated `AuthResult` value object for clearer, type-safe handoff between auth strategies and the security middleware.
+* **Consolidated Middleware Hook Types**: `HOOK_TYPES` and `HOOK_OPERATION_TYPES` are now derived from a single source of truth, eliminating drift between the two lists.
+* **Puma Thread Pool Tuning**: Standalone HTTP stream transport now configures the Puma thread pool explicitly for more predictable concurrency behavior.
+* **Event Store Offset Tracking**: Replaced the O(n) event store index rebuild with O(1) offset tracking, reducing overhead for sessions with long event histories.
+* **HTTP Stream Request Tracking**: Removed the redundant `@request_mutex` from HTTP stream request tracking and simplified the surrounding locking.
+* **Handlers::Core Cleanup**: Renamed misleading identifiers and removed dead legacy branches in `Handlers::Core`.
+* **General Complexity Reduction**: Reduced accidental complexity across six refactoring targets in the core request path.
+
+### Fixed
+
+* **TokenStore Read-After-Write Consistency**: Closed a read-after-write consistency hole in `TokenStore` so concurrent tokenization and resolution no longer race.
 
 ## [0.4.0] – 2026-04-10
 

data/README.md

@@ -15,6 +15,7 @@ VectorMCP is a Ruby implementation of the Model Context Protocol (MCP) server-si
 - Rack and Rails mounting through `server.rack_app`
 - Opt-in authentication and authorization, structured logging, and middleware hooks
 - Image-aware tools/resources/prompts, roots, and server-initiated sampling
+- Token-based field anonymization middleware to keep sensitive values out of LLM context
 
 ## Requirements
 
@@ -188,10 +189,27 @@ server.enable_authentication!(strategy: :custom) do |request|
 end
 ```
 
+For MCP clients that speak OAuth 2.1 (e.g. Claude Desktop), pass a `resource_metadata_url:` to turn on RFC 9728 discovery. Unauthenticated requests to `/mcp` return `401` with a `WWW-Authenticate` header pointing at the configured metadata document, and the client drives the rest of the OAuth dance automatically. See [docs/oauth_resource_server.md](./docs/oauth_resource_server.md) for the feature reference and [docs/rails_oauth_integration.md](./docs/rails_oauth_integration.md) for a full Rails + Doorkeeper recipe.
+
 Middleware can hook into tool, resource, prompt, sampling, auth, and transport events, including `before_auth`, `after_auth`, `on_auth_error`, `before_request`, `after_response`, and `on_transport_error`.
 
 See [security/README.md](./security/README.md) for the full security guide.
 
+### Field Anonymization
+
+Keep sensitive string values out of the LLM context by substituting them with stable opaque tokens. Values are tokenized on outbound tool results and restored on inbound tool arguments, so the LLM sees only tokens while your handlers receive the original data.
+
+```ruby
+anonymizer = VectorMCP::Middleware::Anonymizer.new(
+  store: VectorMCP::TokenStore.new,
+  field_rules: [
+    { pattern: /email/i, prefix: "EMAIL" },
+    { pattern: /\bssn\b/i, prefix: "SSN" }
+  ]
+)
+anonymizer.install_on(server)
+```
+
 ## Transport Notes
 
 - VectorMCP ships with streamable HTTP as its built-in transport
@@ -223,6 +241,8 @@ curl -X POST http://localhost:8080/mcp \
 - [CHANGELOG.md](./CHANGELOG.md)
 - [examples/](./examples/)
 - [docs/rails-setup-guide.md](./docs/rails-setup-guide.md)
+- [docs/rails_oauth_integration.md](./docs/rails_oauth_integration.md)
+- [docs/oauth_resource_server.md](./docs/oauth_resource_server.md)
 - [docs/streamable-http-spec-compliance.md](./docs/streamable-http-spec-compliance.md)
 - [security/README.md](./security/README.md)
 - [MCP Specification](https://modelcontextprotocol.io/)

data/lib/vector_mcp/definitions.rb

@@ -29,6 +29,36 @@ module VectorMCP
         }.compact # Remove nil values
       end
 
+      # Class method to create a tool whose input_schema already declares a
+      # base64-encoded image property. Mirrors Resource.from_image_file and
+      # Prompt.with_image_support — keeps schema-building logic with the
+      # definition, not with the registry.
+      #
+      # @param name [String] Unique name for the tool.
+      # @param description [String] Human-readable description.
+      # @param image_parameter [String] Name of the image parameter.
+      # @param additional_parameters [Hash] Additional JSON Schema properties.
+      # @param required_parameters [Array<String>] Required parameter names.
+      # @param handler [Proc] Tool handler block.
+      # @return [Tool]
+      def self.with_image_support(name:, description:, image_parameter: "image",
+                                  additional_parameters: {}, required_parameters: [], &handler)
+        image_property = {
+          type: "string",
+          description: "Base64 encoded image data or file path to image",
+          contentEncoding: "base64",
+          contentMediaType: "image/*"
+        }
+
+        input_schema = {
+          type: "object",
+          properties: { image_parameter => image_property }.merge(additional_parameters),
+          required: required_parameters
+        }
+
+        new(name, description, input_schema, handler)
+      end
+
       # Checks if this tool supports image inputs based on its input schema.
       # @return [Boolean] True if the tool's input schema includes image properties.
       def supports_image_input?

data/lib/vector_mcp/handlers/core.rb

@@ -55,7 +55,7 @@ module VectorMCP
         context = create_tool_context(tool_name, params, session, server)
 
         begin
-          session_context = authenticate_session!(session, server, operation_type: :tool_call, operation_name: tool_name)
+          session_context = authenticate_request!(session, server, operation_type: :tool_call, operation_name: tool_name)
 
           context = server.middleware_manager.execute_hooks(:before_tool_call, context)
           return handle_middleware_error(context) if context.error?
@@ -64,7 +64,7 @@ module VectorMCP
           arguments = context.params["arguments"] || {}
           tool = find_tool!(tool_name, server)
           authorize_action!(session_context, :call, tool, server)
-          validate_input_arguments!(tool_name, tool, arguments)
+          validate_tool_arguments!(tool_name, tool, arguments)
 
           result = execute_tool_handler(tool, arguments, session)
           context.result = build_tool_result(result)
@@ -105,7 +105,7 @@ module VectorMCP
         context = create_resource_context(uri_s, params, session, server)
 
         begin
-          session_context = authenticate_session!(session, server, operation_type: :resource_read, operation_name: uri_s)
+          session_context = authenticate_request!(session, server, operation_type: :resource_read, operation_name: uri_s)
 
           context = server.middleware_manager.execute_hooks(:before_resource_read, context)
           return handle_middleware_error(context) if context.error?
@@ -206,7 +206,7 @@ module VectorMCP
           prompt = fetch_prompt(prompt_name, server)
 
           arguments = context_params["arguments"] || {}
-          validate_arguments!(prompt_name, prompt, arguments)
+          validate_prompt_arguments!(prompt_name, prompt, arguments)
 
           # Call the registered handler after arguments were validated
           result_data = prompt.handler.call(arguments)
@@ -280,7 +280,7 @@ module VectorMCP
       # @param arguments [Hash] The arguments supplied by the client.
       # @return [void]
       # @raise [VectorMCP::InvalidParamsError] if arguments are invalid (e.g., missing, unknown, wrong type).
-      def self.validate_arguments!(prompt_name, prompt, arguments)
+      def self.validate_prompt_arguments!(prompt_name, prompt, arguments)
         ensure_hash!(prompt_name, arguments, "arguments")
 
         arg_defs = prompt.respond_to?(:arguments) ? (prompt.arguments || []) : []
@@ -291,7 +291,7 @@ module VectorMCP
         raise VectorMCP::InvalidParamsError.new("Invalid arguments",
                                                 details: build_invalid_arg_details(prompt_name, missing, unknown))
       end
-      private_class_method :validate_arguments!
+      private_class_method :validate_prompt_arguments!
 
       # Ensures a given value is a Hash.
       # @api private
@@ -369,7 +369,7 @@ module VectorMCP
       # @param arguments [Hash] The arguments supplied by the client.
       # @return [void]
       # @raise [VectorMCP::InvalidParamsError] if arguments fail validation.
-      def self.validate_input_arguments!(tool_name, tool, arguments)
+      def self.validate_tool_arguments!(tool_name, tool, arguments)
         return unless tool.input_schema.is_a?(Hash)
         return if tool.input_schema.empty?
 
@@ -397,41 +397,14 @@ module VectorMCP
           }
         )
       end
-      private_class_method :validate_input_arguments!
+      private_class_method :validate_tool_arguments!
       private_class_method :raise_tool_validation_error
 
-      # Security helper methods
-
-      # Check security for tool access
-      # @api private
-      # @param session [VectorMCP::Session] The current session
-      # @param tool [VectorMCP::Definitions::Tool] The tool being accessed
-      # @param server [VectorMCP::Server] The server instance
-      # @return [Hash] Security check result
-      def self.check_tool_security(session, tool, server)
-        # Extract request context from session for security middleware
-        request = extract_request_from_session(session)
-        server.security_middleware.process_request(request, action: :call, resource: tool)
-      end
-      private_class_method :check_tool_security
-
-      # Check security for resource access
-      # @api private
-      # @param session [VectorMCP::Session] The current session
-      # @param resource [VectorMCP::Definitions::Resource] The resource being accessed
-      # @param server [VectorMCP::Server] The server instance
-      # @return [Hash] Security check result
-      def self.check_resource_security(session, resource, server)
-        request = extract_request_from_session(session)
-        server.security_middleware.process_request(request, action: :read, resource: resource)
-      end
-      private_class_method :check_resource_security
-
       # Extract request context from session for security processing
       # @api private
       # @param session [VectorMCP::Session] The current session
       # @return [Hash] Request context for security middleware
-      def self.extract_request_from_session(session)
+      def self.extract_auth_credentials(session)
         # All sessions should have a request_context - this is enforced by Session initialization
         unless session.respond_to?(:request_context) && session.request_context
           raise VectorMCP::InternalError,
@@ -444,25 +417,7 @@ module VectorMCP
           session_id: session.id
         }
       end
-      private_class_method :extract_request_from_session
-
-      # Handle security failure by raising appropriate error
-      # @api private
-      # @param security_result [Hash] The security check result
-      # @return [void]
-      # @raise [VectorMCP::UnauthorizedError, VectorMCP::ForbiddenError]
-      def self.handle_security_failure(security_result)
-        case security_result[:error_code]
-        when "AUTHENTICATION_REQUIRED"
-          raise VectorMCP::UnauthorizedError, security_result[:error]
-        when "AUTHORIZATION_FAILED"
-          raise VectorMCP::ForbiddenError, security_result[:error]
-        else
-          # Fallback to generic unauthorized error
-          raise VectorMCP::UnauthorizedError, security_result[:error] || "Security check failed"
-        end
-      end
-      private_class_method :handle_security_failure
+      private_class_method :extract_auth_credentials
 
       # Handle middleware error by returning appropriate response or raising error
       # @api private
@@ -499,24 +454,17 @@ module VectorMCP
         tool
       end
 
-      # Resolve the session authentication state before operation middleware runs.
-      def self.authenticate_session!(session, server, operation_type:, operation_name:)
-        request = extract_request_from_session(session)
+      # Authenticate the current request and return the caller's identity.
+      def self.authenticate_request!(session, server, operation_type:, operation_name:)
+        request = extract_auth_credentials(session)
         context = create_auth_context(operation_type, operation_name, request, session, server)
         context = server.middleware_manager.execute_hooks(:before_auth, context)
         raise context.error if context.error?
 
-        request = context.params
-        session_context = if server.security_middleware.respond_to?(:authenticate_request)
-                            server.security_middleware.authenticate_request(request)
-                          else
-                            legacy_result = server.security_middleware.process_request(request)
-                            legacy_result[:session_context]
-                          end
+        session_context = server.security_middleware.authenticate_request(context.params)
         session.security_context = session_context if session.respond_to?(:security_context=)
 
-        auth_required = server.respond_to?(:auth_manager) ? server.auth_manager.required? : false
-        raise VectorMCP::UnauthorizedError, "Authentication required" if auth_required && !session_context.authenticated?
+        raise VectorMCP::UnauthorizedError, "Authentication required" if server.auth_manager.required? && !session_context.authenticated?
 
         context.result = session_context
         server.middleware_manager.execute_hooks(:after_auth, context)
@@ -572,15 +520,9 @@ module VectorMCP
         server.resources[uri_s]
       end
 
-      # Validate resource security
+      # Check authorization and raise ForbiddenError if denied
       def self.authorize_action!(session_context, action, resource, server)
-        authorized = if server.security_middleware.respond_to?(:authorize_action)
-                       server.security_middleware.authorize_action(session_context, action, resource)
-                     else
-                       legacy_result = server.security_middleware.process_request({}, action: action, resource: resource)
-                       legacy_result[:success]
-                     end
-        return if authorized
+        return if server.security_middleware.authorize_action(session_context, action, resource)
 
         raise VectorMCP::ForbiddenError, "Access denied"
       end
@@ -633,7 +575,7 @@ module VectorMCP
         raise error
       end
 
-      private_class_method :handle_middleware_error, :create_tool_context, :find_tool!, :authenticate_session!,
+      private_class_method :handle_middleware_error, :create_tool_context, :find_tool!, :authenticate_request!,
                            :execute_tool_handler, :build_tool_result, :handle_tool_error, :create_resource_context,
                            :find_resource!, :authorize_action!, :execute_resource_handler,
                            :process_resource_content, :handle_resource_error, :create_auth_context,

data/lib/vector_mcp/middleware/anonymizer.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "base"
+require_relative "../token_store"
+require_relative "../util/token_sweeper"
+
+module VectorMCP
+  module Middleware
+    # Middleware that rewrites selected string fields in outbound tool
+    # results into opaque tokens and restores them on inbound tool
+    # invocations. All domain knowledge (which keys to match, token
+    # prefixes, which keys to treat as atomic blobs) is supplied by the
+    # application via the constructor.
+    #
+    # @example Wiring on a server
+    #   anonymizer = VectorMCP::Middleware::Anonymizer.new(
+    #     store:       VectorMCP::TokenStore.new,
+    #     field_rules: [
+    #       { pattern: /\bname\b/i, prefix: "NAME"  },
+    #       { pattern: /email/i,    prefix: "EMAIL" }
+    #     ],
+    #     atomic_keys: /address/i
+    #   )
+    #   anonymizer.install_on(server)
+    class Anonymizer
+      # @param store [VectorMCP::TokenStore] the backing token store.
+      # @param field_rules [Array<Hash>] an array of +{ pattern: Regexp, prefix: String }+
+      #   hashes. The pattern is matched against each Hash key whose value is a String.
+      # @param atomic_keys [Regexp, nil] optional pattern; Hash values whose parent
+      #   key matches are serialized and tokenized as a single opaque unit instead
+      #   of recursed into.
+      def initialize(store:, field_rules:, atomic_keys: nil)
+        raise ArgumentError, "store is required"       if store.nil?
+        raise ArgumentError, "field_rules is required" if field_rules.nil?
+
+        @store = store
+        @field_rules = field_rules.map { |rule| validate_rule!(rule) }.freeze
+        @atomic_keys = atomic_keys
+      end
+
+      # Tokenize sensitive string fields in an outbound payload.
+      #
+      # @param obj [Object] a parsed JSON-like Ruby structure.
+      # @return [Object] a new structure with matched values replaced by tokens.
+      def sweep_outbound(obj)
+        replace_atomic_nodes(obj).then do |shaped|
+          VectorMCP::Util::TokenSweeper.sweep(shaped) do |value, parent_key|
+            rule = rule_for(parent_key)
+            rule ? @store.tokenize(value, prefix: rule[:prefix]) : value
+          end
+        end
+      end
+
+      # Resolve tokens in an inbound payload back to their original values.
+      # Unknown token-shaped strings pass through unchanged.
+      #
+      # @param obj [Object] a parsed JSON-like Ruby structure.
+      # @return [Object] a new structure with tokens resolved to original values.
+      def sweep_inbound(obj)
+        VectorMCP::Util::TokenSweeper.sweep(obj) do |value, _parent_key|
+          if @store.token?(value)
+            resolved = @store.resolve(value)
+            resolved.nil? ? value : resolved
+          else
+            value
+          end
+        end
+      end
+
+      # Middleware hook: rewrite tool arguments before the handler runs.
+      # @param context [VectorMCP::Middleware::Context]
+      def before_tool_call(context)
+        return unless context.params.is_a?(Hash)
+
+        arguments = context.params["arguments"]
+        return unless arguments.is_a?(Hash) || arguments.is_a?(Array)
+
+        context.params = context.params.merge("arguments" => sweep_inbound(arguments))
+      end
+
+      # Middleware hook: tokenize matched fields in the tool result.
+      # @param context [VectorMCP::Middleware::Context]
+      def after_tool_call(context)
+        return if context.result.nil?
+
+        context.result = sweep_outbound(context.result)
+      end
+
+      # Register this anonymizer instance on +server+ for the tool call
+      # lifecycle. Creates a thin adapter class so the middleware manager's
+      # argumentless instantiation can still deliver the configured instance.
+      #
+      # @param server [VectorMCP::Server] the server instance.
+      # @param priority [Integer] middleware priority.
+      # @return [Class] the adapter class registered with the server.
+      def install_on(server, priority: Hook::DEFAULT_PRIORITY)
+        instance = self
+        adapter = Class.new(Base) do
+          define_method(:before_tool_call) { |context| instance.before_tool_call(context) }
+          define_method(:after_tool_call)  { |context| instance.after_tool_call(context) }
+        end
+        server.use_middleware(adapter, %i[before_tool_call after_tool_call], priority: priority)
+        adapter
+      end
+
+      private
+
+      def validate_rule!(rule)
+        unless rule.is_a?(Hash) && rule[:pattern].is_a?(Regexp) && rule[:prefix].is_a?(String)
+          raise ArgumentError,
+                "each field_rule must be a Hash with :pattern (Regexp) and :prefix (String)"
+        end
+
+        rule
+      end
+
+      def rule_for(parent_key)
+        return nil if parent_key.nil?
+
+        key_string = parent_key.to_s
+        @field_rules.find { |rule| rule[:pattern].match?(key_string) }
+      end
+
+      def atomic_match?(parent_key)
+        return false if @atomic_keys.nil? || parent_key.nil?
+
+        @atomic_keys.match?(parent_key.to_s)
+      end
+
+      # First pass: collapse Hash nodes whose parent key matches +atomic_keys+
+      # into a single tokenized string. A fresh traversal avoids entanglement
+      # with the field-rule sweep that runs afterwards.
+      def replace_atomic_nodes(obj, parent_key = nil, visited = {}.compare_by_identity)
+        case obj
+        when Hash
+          return obj if visited[obj]
+
+          if atomic_match?(parent_key)
+            @store.tokenize(canonical_json(obj), prefix: atomic_prefix_for(parent_key))
+          else
+            visited[obj] = true
+            begin
+              obj.each_with_object({}) do |(key, value), out|
+                out[key] = replace_atomic_nodes(value, key, visited)
+              end
+            ensure
+              visited.delete(obj)
+            end
+          end
+        when Array
+          return obj if visited[obj]
+
+          visited[obj] = true
+          begin
+            obj.map { |element| replace_atomic_nodes(element, parent_key, visited) }
+          ensure
+            visited.delete(obj)
+          end
+        else
+          obj
+        end
+      end
+
+      # Atomic nodes use the prefix of the first field rule whose pattern
+      # matches the enclosing key. If no field rule matches, fall back to a
+      # neutral default so the token is still well-formed.
+      def atomic_prefix_for(parent_key)
+        rule_for(parent_key)&.dig(:prefix) || "ATOM"
+      end
+
+      def canonical_json(hash)
+        JSON.generate(canonicalize(hash))
+      end
+
+      def canonicalize(obj)
+        case obj
+        when Hash  then obj.keys.map(&:to_s).sort.to_h { |k| [k, canonicalize(obj[k] || obj[k.to_sym])] }
+        when Array then obj.map { |element| canonicalize(element) }
+        else obj
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/middleware/hook.rb

@@ -4,7 +4,7 @@ module VectorMCP
   module Middleware
     # Represents a single middleware hook with priority and execution logic
     class Hook
-      attr_reader :middleware_class, :hook_type, :priority, :conditions
+      attr_reader :middleware_class, :hook_type, :operation_type, :priority, :conditions
 
       # Default priority for middleware (lower numbers execute first)
       DEFAULT_PRIORITY = 100
@@ -21,6 +21,8 @@ module VectorMCP
 
         validate_hook_type!
         validate_middleware_class!
+
+        @operation_type = HOOK_OPERATION_TYPES[@hook_type]
       end
 
       # Execute this hook with the given context
@@ -72,12 +74,12 @@ module VectorMCP
         raise ArgumentError, "middleware_class must inherit from VectorMCP::Middleware::Base"
       end
 
+      # Whether this hook's operation_type matches the context's. Transport- and
+      # auth-level hooks (operation_type == nil) match any context.
       def matches_operation_type?(context)
-        operation_prefix = @hook_type.split("_")[1..].join("_")
-
-        return true if transport_or_auth_hook?(operation_prefix)
+        return true if @operation_type.nil?
 
-        operation_matches?(operation_prefix, context.operation_type)
+        context.operation_type == @operation_type
       end
 
       def condition_matches?(key, value, context)
@@ -91,25 +93,6 @@ module VectorMCP
         end
       end
 
-      def transport_or_auth_hook?(operation_prefix)
-        %w[request response transport_error auth auth_error].include?(operation_prefix)
-      end
-
-      def operation_matches?(operation_prefix, operation_type)
-        case operation_prefix
-        when "tool_call", "tool_error"
-          operation_type == :tool_call
-        when "resource_read", "resource_error"
-          operation_type == :resource_read
-        when "prompt_get", "prompt_error"
-          operation_type == :prompt_get
-        when "sampling_request", "sampling_response", "sampling_error"
-          operation_type == :sampling
-        else
-          true
-        end
-      end
-
       def operation_condition_matches?(key, value, context)
         included = Array(value).include?(context.operation_name)
         key == :only_operations ? included : !included

data/lib/vector_mcp/middleware.rb

@@ -12,15 +12,32 @@ module VectorMCP
   # Middleware system for pluggable hooks around MCP operations
   # Allows developers to add custom behavior without modifying core code
   module Middleware
-    # Hook types available in the system
-    HOOK_TYPES = %w[
-      before_tool_call after_tool_call on_tool_error
-      before_resource_read after_resource_read on_resource_error
-      before_prompt_get after_prompt_get on_prompt_error
-      before_sampling_request after_sampling_response on_sampling_error
-      before_request after_response on_transport_error
-      before_auth after_auth on_auth_error
-    ].freeze
+    # Maps each hook type to the operation_type it matches. `nil` means the
+    # hook is transport- or auth-level and matches any operation_type.
+    # This is the single source of truth — HOOK_TYPES is derived from it.
+    HOOK_OPERATION_TYPES = {
+      "before_tool_call" => :tool_call,
+      "after_tool_call" => :tool_call,
+      "on_tool_error" => :tool_call,
+      "before_resource_read" => :resource_read,
+      "after_resource_read" => :resource_read,
+      "on_resource_error" => :resource_read,
+      "before_prompt_get" => :prompt_get,
+      "after_prompt_get" => :prompt_get,
+      "on_prompt_error" => :prompt_get,
+      "before_sampling_request" => :sampling,
+      "after_sampling_response" => :sampling,
+      "on_sampling_error" => :sampling,
+      "before_request" => nil,
+      "after_response" => nil,
+      "on_transport_error" => nil,
+      "before_auth" => nil,
+      "after_auth" => nil,
+      "on_auth_error" => nil
+    }.freeze
+
+    # Hook types available in the system (derived from HOOK_OPERATION_TYPES)
+    HOOK_TYPES = HOOK_OPERATION_TYPES.keys.freeze
 
     # Error raised when invalid hook type is specified
     class InvalidHookTypeError < VectorMCP::Error

data/lib/vector_mcp/security/auth_manager.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "auth_result"
+
 module VectorMCP
   module Security
     # Manages authentication strategies for VectorMCP servers
@@ -42,25 +44,22 @@ module VectorMCP
       # Authenticate a request using the specified or default strategy
       # @param request [Hash] the request object containing headers, params, etc.
       # @param strategy [Symbol] optional strategy override
-      # @return [Object, false] authentication result or false if failed
+      # @return [AuthResult] the authentication outcome
       def authenticate(request, strategy: nil)
-        return { authenticated: true, user: nil } unless @enabled
+        return AuthResult.passthrough unless @enabled
 
         strategy_name = strategy || @default_strategy
         auth_strategy = @strategies[strategy_name]
+        return AuthResult.failure unless auth_strategy
 
-        return { authenticated: false, error: "Unknown strategy: #{strategy_name}" } unless auth_strategy
-
-        begin
-          result = auth_strategy.authenticate(request)
-          if result
-            { authenticated: true, user: result }
-          else
-            { authenticated: false, error: "Authentication failed" }
-          end
-        rescue StandardError => e
-          { authenticated: false, error: "Authentication error: #{e.message}" }
+        result = auth_strategy.authenticate(request)
+        if result == false
+          AuthResult.failure
+        else
+          AuthResult.success(user: result, strategy: strategy_name.to_s)
         end
+      rescue StandardError
+        AuthResult.failure
       end
 
       # Check if authentication is required