vector_mcp 0.4.0 → 0.6.0

data/lib/vector_mcp/server.rb

@@ -72,7 +72,7 @@ module VectorMCP
     SUPPORTED_PROTOCOL_VERSIONS = %w[2025-11-25 2025-03-26 2024-11-05].freeze
 
     attr_reader :logger, :name, :version, :protocol_version, :tools, :resources, :prompts, :roots, :in_flight_requests,
-                :auth_manager, :authorization, :security_middleware, :middleware_manager
+                :auth_manager, :authorization, :security_middleware, :middleware_manager, :oauth_resource_metadata_url
     attr_accessor :transport
 
     # Initializes a new VectorMCP server.
@@ -122,6 +122,7 @@ module VectorMCP
       @auth_manager = Security::AuthManager.new
       @authorization = Security::Authorization.new
       @security_middleware = Security::Middleware.new(@auth_manager, @authorization)
+      @oauth_resource_metadata_url = nil
 
       # Initialize middleware manager
       @middleware_manager = Middleware::Manager.new
@@ -188,28 +189,18 @@ module VectorMCP
     # Enable authentication with specified strategy and configuration
     # @param strategy [Symbol] the authentication strategy (:api_key, :jwt, :custom)
     # @param options [Hash] strategy-specific configuration options
+    # @option options [String] :resource_metadata_url OAuth 2.1 protected resource metadata URL
+    #   (RFC 9728). When provided, unauthenticated requests to the HTTP Stream transport's MCP
+    #   endpoint return HTTP 401 with a +WWW-Authenticate: Bearer+ header pointing at this URL,
+    #   enabling MCP clients (e.g. Claude Desktop) to discover the authorization server and
+    #   initiate an OAuth 2.1 flow. When omitted (default), auth failures continue to surface
+    #   as JSON-RPC +-32401+ errors — existing behavior is preserved for non-OAuth deployments.
     # @return [void]
     def enable_authentication!(strategy: :api_key, **options, &block)
-      # Clear existing strategies when switching to a new configuration
       clear_auth_strategies unless @auth_manager.strategies.empty?
-
+      extract_oauth_metadata!(options)
       @auth_manager.enable!(default_strategy: strategy)
-
-      case strategy
-      when :api_key
-        add_api_key_auth(options[:keys] || [], allow_query_params: options[:allow_query_params] || false)
-      when :jwt
-        add_jwt_auth(options)
-      when :custom
-        handler = block || options[:handler]
-        raise ArgumentError, "Custom authentication strategy requires a handler block" unless handler
-
-        add_custom_auth(&handler)
-
-      else
-        raise ArgumentError, "Unknown authentication strategy: #{strategy}"
-      end
-
+      register_auth_strategy(strategy, options, block || options.delete(:handler))
       @logger.info("Authentication enabled with strategy: #{strategy}")
     end
 
@@ -217,6 +208,7 @@ module VectorMCP
     # @return [void]
     def disable_authentication!
       @auth_manager.disable!
+      @oauth_resource_metadata_url = nil
       @logger.info("Authentication disabled")
     end
 
@@ -318,6 +310,34 @@ module VectorMCP
 
     private
 
+    # Extract OAuth resource metadata URL from options before they reach strategy constructors
+    # @param options [Hash] the options hash (mutated — :resource_metadata_url is removed)
+    # @return [void]
+    def extract_oauth_metadata!(options)
+      @oauth_resource_metadata_url = options.delete(:resource_metadata_url)
+      warn_on_insecure_oauth_metadata_url(@oauth_resource_metadata_url)
+    end
+
+    # Register the appropriate auth strategy based on the strategy name
+    # @param strategy [Symbol] the strategy type
+    # @param options [Hash] strategy-specific options
+    # @param handler [Proc, nil] custom handler block (for :custom strategy)
+    # @return [void]
+    def register_auth_strategy(strategy, options, handler)
+      case strategy
+      when :api_key
+        add_api_key_auth(options[:keys] || [], allow_query_params: options[:allow_query_params] || false)
+      when :jwt
+        add_jwt_auth(options)
+      when :custom
+        raise ArgumentError, "Custom authentication strategy requires a handler block" unless handler
+
+        add_custom_auth(&handler)
+      else
+        raise ArgumentError, "Unknown authentication strategy: #{strategy}"
+      end
+    end
+
     # Add API key authentication strategy
     # @param keys [Array<String>] array of valid API keys
     # @param allow_query_params [Boolean] whether to accept API keys from query parameters
@@ -350,6 +370,20 @@ module VectorMCP
         @auth_manager.remove_strategy(strategy_name)
       end
     end
+
+    # Emit a warning when the OAuth resource metadata URL is not HTTPS.
+    # We don't raise because local development against http://localhost is a valid use case.
+    # @param url [String, nil] the configured metadata URL
+    # @return [void]
+    def warn_on_insecure_oauth_metadata_url(url)
+      return if url.nil?
+      return if url.start_with?("https://")
+
+      @logger.warn do
+        "[SECURITY] resource_metadata_url is not HTTPS (#{url}). " \
+          "Use HTTPS in production; plaintext is only acceptable for local development."
+      end
+    end
   end
 
   module Transport

data/lib/vector_mcp/session.rb

@@ -17,7 +17,8 @@ module VectorMCP
   # @attr_reader client_capabilities [Hash, nil] Capabilities supported by the client, received during initialization.
   # @attr_reader request_context [RequestContext] The request context for this session.
   class Session
-    attr_reader :server_info, :server_capabilities, :protocol_version, :client_info, :client_capabilities, :server, :transport, :id, :request_context
+    attr_reader :server_info, :server_capabilities, :protocol_version, :client_info, :client_capabilities, :server, :transport, :id,
+                :request_context, :created_at, :last_accessed_at, :metadata
     attr_accessor :data, :security_context # For user-defined session-specific storage and resolved auth context
 
     # Initializes a new session.
@@ -35,6 +36,9 @@ module VectorMCP
       @client_capabilities = nil
       @data = {} # Initialize user data hash
       @security_context = Security::SessionContext.anonymous
+      @created_at = Time.now
+      @last_accessed_at = @created_at
+      @metadata = {} # Transport-owned lifecycle/connection state
       @logger = server.logger
 
       # Initialize request context
@@ -90,14 +94,34 @@ module VectorMCP
       @initialized_state == :succeeded
     end
 
+    # --- Lifecycle (managed by the transport's session manager) ---
+
+    # Records activity on this session, deferring expiry.
+    # @return [void]
+    def touch!
+      @last_accessed_at = Time.now
+    end
+
+    # @param timeout [Numeric] Idle timeout in seconds.
+    # @return [Boolean] True when the session has been idle longer than the timeout.
+    def expired?(timeout)
+      Time.now - @last_accessed_at > timeout
+    end
+
+    # @return [Float] Seconds since the session was created.
+    def age
+      Time.now - @created_at
+    end
+
     # Sets the request context for this session.
-    # This method should be called by transport layers to populate request-specific data.
     #
+    # @deprecated Will be removed in 0.7. Request-scoped data travels on the
+    #   per-request {VectorMCP::Invocation} passed to handlers.
     # @param context [RequestContext, Hash] The request context to set.
-    #   Can be a RequestContext object or a hash of attributes.
     # @return [RequestContext] The newly set request context.
     # @raise [ArgumentError] If the context is not a RequestContext or Hash.
     def request_context=(context)
+      deprecated_request_api(:request_context=)
       @request_context = case context
                          when RequestContext
                            context
@@ -109,53 +133,47 @@ module VectorMCP
     end
 
     # Updates the request context with new data.
-    # This merges the provided attributes with the existing context.
     #
+    # @deprecated Will be removed in 0.7. Use the per-request invocation's
+    #   {VectorMCP::Invocation#update_request_context} instead.
     # @param attributes [Hash] The attributes to merge into the request context.
     # @return [RequestContext] The updated request context.
     def update_request_context(**attributes)
-      current_attrs = @request_context.to_h
-
-      # Deep merge nested hashes like headers and params
-      merged_attrs = current_attrs.dup
-      attributes.each do |key, value|
-        merged_attrs[key] = if value.is_a?(Hash) && current_attrs[key].is_a?(Hash)
-                              current_attrs[key].merge(value)
-                            else
-                              value
-                            end
-      end
-
-      @request_context = RequestContext.new(**merged_attrs)
+      deprecated_request_api(:update_request_context)
+      @request_context = @request_context.merge(attributes)
     end
 
-    # Convenience method to check if the session has request headers.
-    #
-    # @return [Boolean] True if the request context has headers, false otherwise.
+    # @deprecated Will be removed in 0.7. Use the per-request invocation's
+    #   {VectorMCP::Invocation#request_headers?} instead.
+    # @return [Boolean] True if the request context has headers.
     def request_headers?
+      deprecated_request_api(:request_headers?)
       @request_context.headers?
     end
 
-    # Convenience method to check if the session has request parameters.
-    #
-    # @return [Boolean] True if the request context has parameters, false otherwise.
+    # @deprecated Will be removed in 0.7. Use the per-request invocation's
+    #   {VectorMCP::Invocation#request_params?} instead.
+    # @return [Boolean] True if the request context has parameters.
     def request_params?
+      deprecated_request_api(:request_params?)
       @request_context.params?
     end
 
-    # Convenience method to get a request header value.
-    #
+    # @deprecated Will be removed in 0.7. Use the per-request invocation's
+    #   {VectorMCP::Invocation#request_header} instead.
     # @param name [String] The header name.
     # @return [String, nil] The header value or nil if not found.
     def request_header(name)
+      deprecated_request_api(:request_header)
       @request_context.header(name)
     end
 
-    # Convenience method to get a request parameter value.
-    #
+    # @deprecated Will be removed in 0.7. Use the per-request invocation's
+    #   {VectorMCP::Invocation#request_param} instead.
     # @param name [String] The parameter name.
     # @return [String, nil] The parameter value or nil if not found.
     def request_param(name)
+      deprecated_request_api(:request_param)
       @request_context.param(name)
     end
 
@@ -220,6 +238,16 @@ module VectorMCP
 
     private
 
+    # Emit the standard deprecation warning for the request-scoped Session API.
+    # @api private
+    def deprecated_request_api(method_name)
+      VectorMCP.deprecation_warning(
+        "Session##{method_name} is deprecated and will be removed in 0.7; " \
+        "request-scoped data lives on the per-request invocation passed to handlers " \
+        "(e.g. invocation.request_header)"
+      )
+    end
+
     # Validates that sampling can be performed on this session.
     # @api private
     # @raise [StandardError, InitializationError] if preconditions are not met.

data/lib/vector_mcp/token_store.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+require "securerandom"
+
+module VectorMCP
+  # Thread-safe bidirectional store mapping arbitrary string values to opaque
+  # tokens and back. The store has no knowledge of domain semantics: callers
+  # supply the prefix, and the store guarantees that the same (value, prefix)
+  # pair always yields the same token within its lifetime.
+  class TokenStore
+    # Regexp describing the token format emitted by {#tokenize}.
+    TOKEN_PATTERN = /\A[A-Z]+_[0-9A-F]{8}\z/
+
+    def initialize
+      @forward = Concurrent::Hash.new
+      @reverse = Concurrent::Hash.new
+      @mutex = Mutex.new
+    end
+
+    # Return an opaque token for +value+. Calling this repeatedly with the
+    # same +value+ and +prefix+ returns the same token.
+    #
+    # @param value [String] the value to tokenize.
+    # @param prefix [String] the token prefix (uppercase recommended).
+    # @return [String] a token of the form +"PREFIX_XXXXXXXX"+.
+    def tokenize(value, prefix:)
+      key = [prefix, value]
+      existing = @forward[key]
+      return existing if existing
+
+      @mutex.synchronize do
+        existing = @forward[key]
+        return existing if existing
+
+        token = generate_token(prefix)
+        # Populate the reverse map first so any thread that observes the
+        # token in @forward can always resolve it.
+        @reverse[token] = value
+        @forward[key] = token
+        token
+      end
+    end
+
+    # Resolve a token back to its original value.
+    #
+    # @param token [String] a token previously returned by {#tokenize}.
+    # @return [String, nil] the original value, or +nil+ if unknown.
+    def resolve(token)
+      @reverse[token]
+    end
+
+    # Predicate: does +string+ look like a token issued by this class?
+    # This check is purely structural and does not consult the store.
+    #
+    # @param string [Object] the value to test.
+    # @return [Boolean]
+    def token?(string)
+      string.is_a?(String) && TOKEN_PATTERN.match?(string)
+    end
+
+    # Remove all mappings. Intended for test teardown.
+    # @return [void]
+    def clear
+      @mutex.synchronize do
+        @forward.clear
+        @reverse.clear
+      end
+    end
+
+    private
+
+    def generate_token(prefix)
+      loop do
+        candidate = "#{prefix}_#{SecureRandom.hex(4).upcase}"
+        return candidate unless @reverse.key?(candidate)
+      end
+    end
+  end
+end

data/lib/vector_mcp/transport/base_session_manager.rb

@@ -11,21 +11,6 @@ module VectorMCP
     #
     # @abstract Subclass and implement transport-specific methods
     class BaseSessionManager
-      # Session data structure for unified session management
-      Session = Struct.new(:id, :context, :created_at, :last_accessed_at, :metadata) do
-        def touch!
-          self.last_accessed_at = Time.now
-        end
-
-        def expired?(timeout)
-          Time.now - last_accessed_at > timeout
-        end
-
-        def age
-          Time.now - created_at
-        end
-      end
-
       attr_reader :transport, :session_timeout, :logger
 
       # Initializes a new session manager.
@@ -46,7 +31,7 @@ module VectorMCP
       # Gets an existing session by ID.
       #
       # @param session_id [String] The session ID
-      # @return [Session, nil] The session if found and valid
+      # @return [VectorMCP::Session, nil] The session if found and valid
       def get_session(session_id)
         return nil unless session_id
 
@@ -58,40 +43,29 @@ module VectorMCP
       end
 
       # Gets an existing session or creates a new one.
+      # When a session_id is provided but not found (expired or unknown), returns
+      # nil instead of creating a session with the client-supplied ID — session
+      # IDs are always server-generated (prevents session fixation).
       #
       # @param session_id [String, nil] The session ID (optional)
-      # @return [Session] The existing or newly created session
+      # @return [VectorMCP::Session, nil] The existing session, a newly created one, or nil
       def get_or_create_session(session_id = nil)
         if session_id
-          session = get_session(session_id)
-          return session if session
-
-          # If session_id was provided but not found, create with that ID
-          return create_session(session_id)
+          get_session(session_id)
+        else
+          create_session
         end
-
-        create_session
       end
 
       # Creates a new session.
       #
       # @param session_id [String, nil] Optional specific session ID to use
-      # @return [Session] The newly created session
+      # @return [VectorMCP::Session] The newly created session
       def create_session(session_id = nil)
         session_id ||= generate_session_id
-        now = Time.now
-
-        # Create VectorMCP session context
-        session_context = VectorMCP::Session.new(@transport.server, @transport, id: session_id)
-
-        # Create internal session record with transport-specific metadata
-        session = Session.new(
-          session_id,
-          session_context,
-          now,
-          now,
-          create_session_metadata
-        )
+
+        session = VectorMCP::Session.new(@transport.server, @transport, id: session_id)
+        session.metadata.merge!(create_session_metadata)
 
         @sessions[session_id] = session
 

data/lib/vector_mcp/transport/http_stream/event_store.rb

@@ -36,7 +36,8 @@ module VectorMCP
         def initialize(max_events)
           @max_events = max_events
           @events = Concurrent::Array.new
-          @event_index = Concurrent::Hash.new # event_id -> index for fast lookup
+          @event_index = Concurrent::Hash.new # event_id -> logical position
+          @offset = 0 # number of events shifted off the front
           @current_sequence = Concurrent::AtomicFixnum.new(0)
         end
 
@@ -53,19 +54,15 @@ module VectorMCP
 
           event = Event.new(event_id, data, type, timestamp, session_id, stream_id)
 
-          # Add to events array
+          # Add to events array and record logical position
           @events.push(event)
-
-          # Update index
-          @event_index[event_id] = @events.length - 1
+          @event_index[event_id] = @offset + @events.length - 1
 
           # Maintain circular buffer
           if @events.length > @max_events
             removed_event = @events.shift
             @event_index.delete(removed_event.id)
-
-            # Update all indices after removal
-            @event_index.transform_values! { |index| index - 1 }
+            @offset += 1
           end
 
           event_id
@@ -81,13 +78,13 @@ module VectorMCP
           events = if last_event_id.nil?
                      @events.to_a
                    else
-                     last_index = @event_index[last_event_id]
-                     return [] if last_index.nil?
+                     logical = @event_index[last_event_id]
+                     return [] if logical.nil?
 
-                     start_index = last_index + 1
-                     return [] if start_index >= @events.length
+                     physical = logical - @offset + 1
+                     return [] if physical >= @events.length
 
-                     @events[start_index..]
+                     @events[physical..]
                    end
 
           events = events.select { |e| e.session_id == session_id } if session_id
@@ -100,10 +97,10 @@ module VectorMCP
         # @param event_id [String] The event ID to look up
         # @return [Event, nil] The stored event, or nil if it is no longer retained
         def get_event(event_id)
-          index = @event_index[event_id]
-          return nil if index.nil?
+          logical = @event_index[event_id]
+          return nil if logical.nil?
 
-          @events[index]
+          @events[logical - @offset]
         end
 
         # Gets the total number of stored events.
@@ -141,6 +138,7 @@ module VectorMCP
         def clear
           @events.clear
           @event_index.clear
+          @offset = 0
         end
 
         # Gets statistics about the event store.

data/lib/vector_mcp/transport/http_stream/session_manager.rb

@@ -19,20 +19,9 @@ module VectorMCP
       #
       # @api private
       class SessionManager < BaseSessionManager
-        # HTTP stream session data structure extending base session
-        Session = Struct.new(:id, :context, :created_at, :last_accessed_at, :metadata) do
-          def touch!
-            self.last_accessed_at = Time.now
-          end
-
-          def expired?(timeout)
-            Time.now - last_accessed_at > timeout
-          end
-
-          def age
-            Time.now - created_at
-          end
-
+        # HTTP-streaming connection state, kept in the session's transport
+        # metadata. New sessions are extended with this module at creation.
+        module SessionStreaming
           def streaming?
             !streaming_connection.nil? || !streaming_connections.empty?
           end
@@ -65,28 +54,20 @@ module VectorMCP
           end
         end
 
-        # Initializes a new HTTP stream session manager.
+        # Creates a new session. RequestContext.from_rack_env handles nil
+        # rack_env by falling back to a minimal context, so we don't need to
+        # branch here.
         #
-        # @param transport [HttpStream] The parent transport instance
-        # @param session_timeout [Integer] Session timeout in seconds
-
-        # Optimized session creation with reduced object allocation and faster context creation
+        # @return [VectorMCP::Session] The newly created session
         def create_session(session_id = nil, rack_env = nil)
           session_id ||= generate_session_id
-          now = Time.now
-
-          # Optimize session context creation - use cached minimal context when rack_env is nil
-          session_context = if rack_env
-                              create_session_with_context(session_id, rack_env)
-                            else
-                              create_minimal_session_context(session_id)
-                            end
-
-          # Pre-allocate metadata hash for better performance
-          metadata = create_session_metadata
 
-          # Create internal session record with streaming connection metadata
-          session = Session.new(session_id, session_context, now, now, metadata)
+          request_context = VectorMCP::RequestContext.from_rack_env(rack_env, "http_stream")
+          session = VectorMCP::Session.new(
+            @transport.server, @transport, id: session_id, request_context: request_context
+          )
+          session.extend(SessionStreaming)
+          session.metadata.merge!(create_session_metadata)
 
           @sessions[session_id] = session
 
@@ -95,38 +76,16 @@ module VectorMCP
         end
 
         # Override to add rack_env support.
-        # Returns nil when a session_id is provided but not found (expired or unknown).
-        # Callers are responsible for returning 404 in that case.
+        # Returns nil when a session_id is provided but not found (expired or
+        # unknown) — callers are responsible for returning 404 in that case.
+        # Request-scoped data is never written onto an existing session; each
+        # request carries its own context via the Invocation built at dispatch.
         def get_or_create_session(session_id = nil, rack_env = nil)
           if session_id
-            session = get_session(session_id)
-            if session
-              # Update existing session context if rack_env is provided
-              if rack_env
-                request_context = VectorMCP::RequestContext.from_rack_env(rack_env, "http_stream")
-                session.context.request_context = request_context
-              end
-              return session
-            end
-
-            # Session ID provided but not found — signal 404 to caller
-            return nil
+            get_session(session_id)
+          else
+            create_session(nil, rack_env)
           end
-
-          create_session(nil, rack_env)
-        end
-
-        # Creates a VectorMCP::Session with proper request context from Rack environment
-        def create_session_with_context(session_id, rack_env)
-          request_context = VectorMCP::RequestContext.from_rack_env(rack_env, "http_stream")
-          VectorMCP::Session.new(@transport.server, @transport, id: session_id, request_context: request_context)
-        end
-
-        # Creates a minimal session context for each session (no caching to prevent contamination)
-        def create_minimal_session_context(session_id)
-          # Create a new minimal context for each session to prevent cross-session contamination
-          minimal_context = VectorMCP::RequestContext.minimal("http_stream")
-          VectorMCP::Session.new(@transport.server, @transport, id: session_id, request_context: minimal_context)
         end
 
         # Terminates a session by ID.

data/lib/vector_mcp/transport/http_stream/stream_handler.rb

@@ -49,7 +49,7 @@ module VectorMCP
         # Handles a streaming request (GET request for SSE).
         #
         # @param env [Hash] The Rack environment
-        # @param session [SessionManager::Session] The session for this request
+        # @param session [VectorMCP::Session] The session for this request
         # @return [Array] Rack response triplet for SSE
         def handle_streaming_request(env, session)
           last_event_id = extract_last_event_id(env)
@@ -65,7 +65,7 @@ module VectorMCP
 
         # Sends a message to a specific session.
         #
-        # @param session [SessionManager::Session] The target session
+        # @param session [VectorMCP::Session] The target session
         # @param message [Hash] The message to send
         # @return [Boolean] True if message was sent successfully
         def send_message_to_session(session, message)
@@ -141,7 +141,7 @@ module VectorMCP
 
         # Creates an SSE stream for a session.
         #
-        # @param session [SessionManager::Session] The session
+        # @param session [VectorMCP::Session] The session
         # @param last_event_id [String, nil] The last event ID for resumability
         # @param origin [Symbol] The stream origin (:get or :post)
         # @return [Enumerator] SSE stream enumerator
@@ -172,7 +172,7 @@ module VectorMCP
 
         # Streams events to a client.
         #
-        # @param session [SessionManager::Session] The session
+        # @param session [VectorMCP::Session] The session
         # @param yielder [Enumerator::Yielder] The SSE yielder
         # @param last_event_id [String, nil] The last event ID for resumability
         # @param stream_id [String] The unique stream identifier
@@ -193,7 +193,7 @@ module VectorMCP
         #
         # @param yielder [Enumerator::Yielder] The SSE yielder
         # @param last_event_id [String] The last event ID received by client
-        # @param session [SessionManager::Session] The session to filter events for
+        # @param session [VectorMCP::Session] The session to filter events for
         # @param stream_id [String] The logical stream ID being resumed
         # @return [void]
         def replay_events(yielder, last_event_id, session, stream_id)
@@ -212,7 +212,7 @@ module VectorMCP
 
         # Keeps the connection alive with periodic heartbeat events.
         #
-        # @param session [SessionManager::Session] The session
+        # @param session [VectorMCP::Session] The session
         # @param yielder [Enumerator::Yielder] The SSE yielder
         # @param stream_id [String] The stream ID for event storage
         # @return [void]
@@ -274,7 +274,7 @@ module VectorMCP
 
         # Cleans up a specific connection.
         #
-        # @param session [SessionManager::Session] The session to clean up
+        # @param session [VectorMCP::Session] The session to clean up
         # @return [void]
         def cleanup_connection(session, connection = nil)
           connection ||= session.streaming_connection