vector_mcp 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8125dfaaa8d0965448eac78401a013a1f5e41292f29141a72c44fca6dbb96cba
-  data.tar.gz: cef6523bbd0c43e969102f5776f6bcb5f2e6a9e10507b4faee1839258fe7f39f
+  metadata.gz: '09966af580b3bf36b9e17f89ef7b592391c42e63b974a17a1db6a852466b9a56'
+  data.tar.gz: 0d04775542e96421bed373179fbfb13864ddfb0aa8256eabea4fddf966d47860
 SHA512:
-  metadata.gz: 6dafbddbeeb279f3232ad45c979b94b92266b1c05060f057dd747bc51ad6cc290da9c30886c9d72cee0445554445cf78e963efd354481974b7b875a5c98e0d21
-  data.tar.gz: 68003e44e084dc40cef4ae04add212901c65056d5432a18aad00550fc8055537812693b915b1f6b00c7e409178ea0801d54f3c9fc3a350c3cca5c65f9afcf700
+  metadata.gz: 33da62c2ffd5dcab4f5e0f7a74426e52885effb4d09c0d82cb479611df838401bfb0de9edb2777a7bb9f21cca190499fa33ff25ee14c46c42a26183b58efa152
+  data.tar.gz: 695aa730c3116bdad34191e3b2b38a0ffea1f10772a2b0e27306f2044b934ab7f576999c13c7bf7568a904af8f82eb8c144830e4a4aebd3aaaec4e8997865430

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.6.0] – 2026-07-19
+
+### Added
+
+* **Per-request `VectorMCP::Invocation`**: Each incoming request is now dispatched through its own request-scoped view of the session, carrying that request's `RequestContext` and resolved `Security::SessionContext`. Handlers receive it as their `session` argument; it delegates all session-lived state (`id`, `data`, `initialize!`, `sample`, ...) and additionally exposes the resolved auth API directly (`user`, `authenticated?`, `can?`, ...).
+* **`RequestContext.coerce` and hash-style access**: `RequestContext` is now the single normalization boundary for authentication. It coerces legacy request shapes (raw Rack env, `{headers:, params:}` hashes) in one place and supports `[]`/`dig`/`key?` so custom auth handlers written against the legacy request hash keep working unchanged.
+* **Session lifecycle on `VectorMCP::Session`**: `created_at`, `last_accessed_at`, `touch!`, `expired?(timeout)`, `age`, and a transport-owned `metadata` hash.
+
+### Changed
+
+* **Security fix — request identity isolation**: Concurrent POSTs on one session could previously be authenticated against each other's headers, because request data was stored as mutable state on the shared session. Request-scoped data now travels on the per-request `Invocation` and is never written onto the session.
+* **One `Session` class**: The transport-internal `Session` wrapper structs (in `BaseSessionManager` and `HttpStream::SessionManager`) are gone; session managers store and return `VectorMCP::Session` directly. HTTP streaming connection state lives in the `SessionManager::SessionStreaming` module.
+* **Unified handler interface**: Resource handlers' second argument is now the per-request invocation instead of a bare `Security::SessionContext`. Existing handlers keep working — the invocation forwards the full auth API (`user`, `authenticated?`, `can?`, `user_identifier`, ...; note: not `to_h`) — and additionally gain access to session identity and request data.
+* **Session managers no longer auto-create sessions from client-supplied IDs** (session-fixation hardening in `BaseSessionManager`, matching the existing HTTP stream behavior).
+* Authentication strategies consume `RequestContext` directly; the auth request no longer carries the undocumented `:session_id` key.
+
+### Deprecated (removal in 0.7)
+
+* The request-scoped API on `Session`: `request_context=`, `update_request_context`, `request_headers?`, `request_params?`, `request_header`, `request_param`. These now emit warnings via `VectorMCP.deprecation_warning`; use the per-request invocation passed to handlers instead.
+* The third `session_id` argument of `Server#handle_message` (now optional, defaults to `session.id`; silent deprecation).
+
 ## [0.5.0] – 2026-04-22
 
 ### Added

data/README.md

@@ -14,6 +14,7 @@ VectorMCP is a Ruby implementation of the Model Context Protocol (MCP) server-si
 - Class-based tools via `VectorMCP::Tool`, plus the original block-based `register_tool` API
 - Rack and Rails mounting through `server.rack_app`
 - Opt-in authentication and authorization, structured logging, and middleware hooks
+- Request-scoped identity: every request is dispatched through its own invocation, so concurrent requests on one session can never observe each other's headers or auth
 - Image-aware tools/resources/prompts, roots, and server-initiated sampling
 - Token-based field anonymization middleware to keep sensitive values out of LLM context
 
@@ -162,6 +163,24 @@ end
 
 `VectorMCP::Tool` also supports `type: :date` and `type: :datetime`, which are validated as strings in JSON Schema and coerced to `Date` and `Time` before `#call` runs.
 
+Handlers that take a second argument receive the per-request invocation, which exposes session identity, the request's headers/params, and the authenticated user in one place:
+
+```ruby
+server.register_tool(
+  name: "whoami",
+  description: "Reports the caller's identity",
+  input_schema: { type: "object", properties: {} }
+) do |_args, invocation|
+  {
+    session: invocation.id,
+    user: invocation.user,
+    api_key_header: invocation.request_header("X-API-Key")
+  }
+end
+```
+
+Resource handlers get the same invocation as their second argument (it also answers the familiar `user` / `authenticated?` / `can?` queries, so handlers written against the older security-context argument keep working unchanged).
+
 ## Security and Middleware
 
 VectorMCP keeps security opt-in, but the primitives are built in:

data/lib/vector_mcp/handlers/core.rb

@@ -114,7 +114,7 @@ module VectorMCP
           resource = find_resource!(uri_s, server)
           authorize_action!(session_context, :read, resource, server)
 
-          content_raw = execute_resource_handler(resource, context.params, session_context)
+          content_raw = execute_resource_handler(resource, context.params, session)
           contents = process_resource_content(content_raw, resource, uri_s)
 
           context.result = { contents: contents }
@@ -400,10 +400,10 @@ module VectorMCP
       private_class_method :validate_tool_arguments!
       private_class_method :raise_tool_validation_error
 
-      # Extract request context from session for security processing
+      # Extract the request context from the session for security processing.
       # @api private
       # @param session [VectorMCP::Session] The current session
-      # @return [Hash] Request context for security middleware
+      # @return [VectorMCP::RequestContext] Request context for security middleware
       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
@@ -411,11 +411,7 @@ module VectorMCP
                 "Session missing request_context - transport layer integration error. Session ID: #{session.id}"
         end
 
-        {
-          headers: session.request_context.headers,
-          params: session.request_context.params,
-          session_id: session.id
-        }
+        session.request_context
       end
       private_class_method :extract_auth_credentials
 
@@ -457,12 +453,14 @@ module VectorMCP
       # 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)
+        # before_auth middleware hooks see (and may modify) the request as a hash;
+        # AuthManager coerces it back into a RequestContext at its boundary.
+        context = create_auth_context(operation_type, operation_name, request.to_h, session, server)
         context = server.middleware_manager.execute_hooks(:before_auth, context)
         raise context.error if context.error?
 
         session_context = server.security_middleware.authenticate_request(context.params)
-        session.security_context = session_context if session.respond_to?(:security_context=)
+        session.security_context = session_context
 
         raise VectorMCP::UnauthorizedError, "Authentication required" if server.auth_manager.required? && !session_context.authenticated?
 
@@ -527,12 +525,15 @@ module VectorMCP
         raise VectorMCP::ForbiddenError, "Access denied"
       end
 
-      # Execute resource handler with proper arity handling
-      def self.execute_resource_handler(resource, params, session_context)
+      # Execute resource handler with proper arity handling.
+      # The second argument is the per-request invocation, which also exposes
+      # the SessionContext auth API for handlers written against the legacy
+      # (params, session_context) signature.
+      def self.execute_resource_handler(resource, params, invocation)
         if [1, -1].include?(resource.handler.arity)
           resource.handler.call(params)
         else
-          resource.handler.call(params, session_context)
+          resource.handler.call(params, invocation)
         end
       end
 

data/lib/vector_mcp/invocation.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "request_context"
+require_relative "security/session_context"
+
+module VectorMCP
+  # A per-request view of a {Session}.
+  #
+  # Carries the request-scoped state — the incoming request's
+  # {RequestContext} and the {Security::SessionContext} resolved for it —
+  # while delegating session-lived state (identity, initialization,
+  # user data, sampling) to the underlying session. Transports build one
+  # Invocation per incoming request and pass it through message dispatch,
+  # so concurrent requests on the same session each observe their own
+  # request data and authentication result.
+  #
+  # The Invocation intentionally quacks like a {Session}: tool handlers and
+  # request/notification hooks receive it as their `session` argument and
+  # can keep using `session.id`, `session.data`, `session.sample`,
+  # `session.request_header`, and `session.security_context` unchanged.
+  class Invocation
+    extend Forwardable
+
+    # @return [VectorMCP::Session] the underlying session this request belongs to
+    attr_reader :session
+
+    # @return [VectorMCP::RequestContext] this request's context (headers, params, ...)
+    attr_reader :request_context
+
+    # @return [VectorMCP::Security::SessionContext] the security context resolved for this request
+    attr_accessor :security_context
+
+    def_delegators :@session,
+                   :id, :server, :transport, :data,
+                   :initialized?, :initialize!, :sample,
+                   :server_info, :server_capabilities, :protocol_version,
+                   :client_info, :client_capabilities
+
+    # The resolved auth API is exposed directly so handlers written against
+    # Security::SessionContext (the legacy second argument of resource
+    # handlers) keep working when they receive the invocation instead.
+    def_delegators :@security_context,
+                   :user, :authenticated, :authenticated?, :auth_strategy, :authenticated_at,
+                   :permissions, :can?, :can_access?, :add_permission, :add_permissions,
+                   :remove_permission, :clear_permissions, :user_identifier, :auth_method,
+                   :auth_recent?
+
+    # @param session [VectorMCP::Session] the session the request arrived on
+    # @param request_context [RequestContext, Hash, nil] this request's context;
+    #   defaults to the session's stored context when not provided
+    def initialize(session, request_context: nil)
+      @session = session
+      @request_context = request_context ? RequestContext.coerce(request_context) : session.request_context
+      @security_context = Security::SessionContext.anonymous
+    end
+
+    # Replace this request's context (e.g. from middleware).
+    # @param context [RequestContext, Hash] the new request context
+    def request_context=(context)
+      @request_context = RequestContext.coerce(context)
+    end
+
+    # Merge attributes into this request's context.
+    # @param attributes [Hash] attributes to merge
+    # @return [RequestContext] the updated request context
+    def update_request_context(**attributes)
+      @request_context = @request_context.merge(attributes)
+    end
+
+    # @return [Boolean] whether this request carried any headers
+    def request_headers?
+      @request_context.headers?
+    end
+
+    # @return [Boolean] whether this request carried any query parameters
+    def request_params?
+      @request_context.params?
+    end
+
+    # @param name [String] the header name
+    # @return [String, nil] the header value for this request
+    def request_header(name)
+      @request_context.header(name)
+    end
+
+    # @param name [String] the parameter name
+    # @return [String, nil] the parameter value for this request
+    def request_param(name)
+      @request_context.param(name)
+    end
+
+    # Invocations compare by their underlying session, so collections that
+    # deduplicate sessions (e.g. prompt subscribers) treat every request
+    # view of one session as the same subscriber.
+    def ==(other)
+      other_session = other.is_a?(Invocation) ? other.session : other
+      @session == other_session
+    end
+    alias eql? ==
+
+    def hash
+      @session.hash
+    end
+  end
+end

data/lib/vector_mcp/request_context.rb

@@ -91,6 +91,25 @@ module VectorMCP
       http_methods.include?(@method.upcase)
     end
 
+    # Return a new context with the given attributes merged in. Nested hashes
+    # (headers, params, transport_metadata) are merged key-wise; scalar
+    # attributes are replaced.
+    #
+    # @param attributes [Hash] attributes to merge
+    # @return [RequestContext] a new, merged context
+    def merge(attributes)
+      current = to_h
+      merged = current.dup
+      attributes.each do |key, value|
+        merged[key] = if value.is_a?(Hash) && current[key].is_a?(Hash)
+                        current[key].merge(value)
+                      else
+                        value
+                      end
+      end
+      RequestContext.new(**merged)
+    end
+
     # Create a minimal request context for non-HTTP transports.
     # This is useful for non-HTTP transports or testing contexts.
     #
@@ -106,6 +125,73 @@ module VectorMCP
       )
     end
 
+    # Coerce an arbitrary request representation into a RequestContext.
+    # This is the single boundary where legacy request shapes (raw Rack
+    # environments, `{headers:, params:}` hashes with symbol or string keys)
+    # are converted; everything downstream of authentication trusts this type.
+    #
+    # @param request [RequestContext, Hash] the request to coerce
+    # @param transport_type [String] transport identifier used when building from a Rack env
+    # @return [RequestContext]
+    # @raise [ArgumentError] if the input cannot be coerced
+    def self.coerce(request, transport_type = "http")
+      case request
+      when RequestContext
+        request
+      when Hash
+        return from_rack_env(request, transport_type) if request.key?("REQUEST_METHOD")
+
+        from_normalized_hash(request)
+      else
+        raise ArgumentError, "Cannot coerce #{request.class} into a VectorMCP::RequestContext"
+      end
+    end
+
+    # Build a context from a legacy `{headers:, params:, ...}` hash with either
+    # symbol or string keys.
+    # @api private
+    def self.from_normalized_hash(hash)
+      fetch = ->(key) { hash[key] || hash[key.to_s] }
+      new(
+        headers: fetch.call(:headers) || {},
+        params: fetch.call(:params) || {},
+        method: fetch.call(:method),
+        path: fetch.call(:path),
+        transport_metadata: fetch.call(:transport_metadata) || {}
+      )
+    end
+    private_class_method :from_normalized_hash
+
+    # Hash-style read access for compatibility with custom authentication
+    # handlers written against the legacy `{headers:, params:}` request hash.
+    #
+    # @param key [String, Symbol] one of :headers, :params, :method, :path, :transport_metadata
+    # @return [Object, nil]
+    def [](key)
+      hash_view[key.to_sym]
+    end
+
+    # @param key [String, Symbol] the top-level key to check
+    # @return [Boolean]
+    def key?(key)
+      hash_view.key?(key.to_sym)
+    end
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+
+    # Dig into the context like a nested hash, e.g. `context.dig(:headers, "X-API-Key")`.
+    #
+    # @param key [String, Symbol] the top-level key
+    # @param rest [Array] further keys passed to the nested value's #dig
+    # @return [Object, nil]
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty?
+
+      value&.dig(*rest)
+    end
+
     # Create a request context from a Rack environment.
     # This is a convenience method for HTTP-based transports.
     #
@@ -149,25 +235,22 @@ module VectorMCP
 
     private
 
-    # Normalize headers to ensure consistent format.
-    #
-    # @param headers [Hash] Raw headers hash
-    # @return [Hash] Normalized headers hash
-    def normalize_headers(headers)
-      return {} unless headers.is_a?(Hash)
-
-      headers.transform_keys(&:to_s).transform_values { |v| v.nil? ? "" : v.to_s }
+    # Memoized nested-hash view backing the hash-style read accessors.
+    def hash_view
+      @hash_view ||= to_h.freeze
     end
 
-    # Normalize parameters to ensure consistent format.
+    # Normalize a headers/params hash to string keys and string values.
     #
-    # @param params [Hash] Raw parameters hash
-    # @return [Hash] Normalized parameters hash
-    def normalize_params(params)
-      return {} unless params.is_a?(Hash)
+    # @param hash [Hash] Raw hash
+    # @return [Hash] Normalized hash
+    def normalize_string_map(hash)
+      return {} unless hash.is_a?(Hash)
 
-      params.transform_keys(&:to_s).transform_values { |v| v.nil? ? "" : v.to_s }
+      hash.transform_keys(&:to_s).transform_values { |v| v.nil? ? "" : v.to_s }
     end
+    alias normalize_headers normalize_string_map
+    alias normalize_params normalize_string_map
 
     # Normalize transport metadata to ensure consistent format.
     #

data/lib/vector_mcp/security/auth_manager.rb

@@ -42,7 +42,9 @@ module VectorMCP
       end
 
       # Authenticate a request using the specified or default strategy
-      # @param request [Hash] the request object containing headers, params, etc.
+      # @param request [VectorMCP::RequestContext, Hash] the request. Legacy hash
+      #   shapes (raw Rack env, {headers:, params:}) are coerced here — the single
+      #   normalization boundary for the authentication pipeline.
       # @param strategy [Symbol] optional strategy override
       # @return [AuthResult] the authentication outcome
       def authenticate(request, strategy: nil)
@@ -52,7 +54,7 @@ module VectorMCP
         auth_strategy = @strategies[strategy_name]
         return AuthResult.failure unless auth_strategy
 
-        result = auth_strategy.authenticate(request)
+        result = auth_strategy.authenticate(VectorMCP::RequestContext.coerce(request))
         if result == false
           AuthResult.failure
         else

data/lib/vector_mcp/security/middleware.rb

@@ -73,25 +73,6 @@ module VectorMCP
         }
       end
 
-      # Create a request object from different transport formats
-      # @param transport_request [Object] the transport-specific request
-      # @return [Hash] normalized request object
-      def normalize_request(transport_request)
-        case transport_request
-        when Hash
-          # Check if it's a Rack environment (has REQUEST_METHOD key)
-          if transport_request.key?("REQUEST_METHOD")
-            extract_from_rack_env(transport_request)
-          else
-            # Already normalized
-            transport_request
-          end
-        else
-          # Extract from transport-specific request (e.g., custom objects)
-          extract_request_data(transport_request)
-        end
-      end
-
       # Check if security is enabled
       # @return [Boolean] true if any security features are enabled
       def security_enabled?
@@ -113,34 +94,6 @@ module VectorMCP
           }
         }
       end
-
-      private
-
-      # Extract request data from transport-specific formats
-      # @param transport_request [Object] the transport request
-      # @return [Hash] extracted request data
-      def extract_request_data(transport_request)
-        # Handle Rack environment (for HTTP transports)
-        if transport_request.respond_to?(:[]) && transport_request["REQUEST_METHOD"]
-          extract_from_rack_env(transport_request)
-        else
-          # Default fallback for non-HTTP request formats
-          { headers: {}, params: {} }
-        end
-      end
-
-      # Extract data from Rack environment
-      # @param env [Hash] the Rack environment
-      # @return [Hash] extracted request data
-      def extract_from_rack_env(env)
-        {
-          headers: VectorMCP::Util.extract_headers_from_rack_env(env),
-          params: VectorMCP::Util.extract_params_from_rack_env(env),
-          method: env["REQUEST_METHOD"],
-          path: env["PATH_INFO"],
-          rack_env: env
-        }
-      end
     end
   end
 end

data/lib/vector_mcp/security/strategies/api_key.rb

@@ -31,10 +31,10 @@ module VectorMCP
         end
 
         # Authenticate a request using API key
-        # @param request [Hash] the request object
+        # @param request [VectorMCP::RequestContext, Hash] the request
         # @return [Hash, false] user info hash or false if authentication failed
         def authenticate(request)
-          api_key = extract_api_key(request)
+          api_key = extract_api_key(VectorMCP::RequestContext.coerce(request))
           return false unless api_key&.length&.positive?
 
           if secure_key_match?(api_key)
@@ -72,57 +72,16 @@ module VectorMCP
           matched
         end
 
-        # Extract API key from various request formats
-        # @param request [Hash] the request object
+        # Extract API key from the request context
+        # @param request [VectorMCP::RequestContext] the request context
         # @return [String, nil] the extracted API key
         def extract_api_key(request)
-          headers = normalize_headers(request)
-
-          from_headers = extract_from_headers(headers)
+          from_headers = extract_from_headers(request.headers)
           return from_headers if from_headers
 
           return nil unless @allow_query_params
 
-          params = normalize_params(request)
-          extract_from_params(params)
-        end
-
-        # Normalize headers to handle different formats
-        # @param request [Hash] the request object
-        # @return [Hash] normalized headers
-        def normalize_headers(request)
-          # Check if it's a Rack environment (has REQUEST_METHOD)
-          if request["REQUEST_METHOD"]
-            extract_headers_from_rack_env(request)
-          else
-            request[:headers] || request["headers"] || {}
-          end
-        end
-
-        # Normalize params to handle different formats
-        # @param request [Hash] the request object
-        # @return [Hash] normalized params
-        def normalize_params(request)
-          # Check if it's a Rack environment (has REQUEST_METHOD)
-          if request["REQUEST_METHOD"]
-            extract_params_from_rack_env(request)
-          else
-            request[:params] || request["params"] || {}
-          end
-        end
-
-        # Extract headers from Rack environment
-        # @param env [Hash] the Rack environment
-        # @return [Hash] normalized headers
-        def extract_headers_from_rack_env(env)
-          VectorMCP::Util.extract_headers_from_rack_env(env)
-        end
-
-        # Extract params from Rack environment
-        # @param env [Hash] the Rack environment
-        # @return [Hash] normalized params
-        def extract_params_from_rack_env(env)
-          VectorMCP::Util.extract_params_from_rack_env(env)
+          extract_from_params(request.params)
         end
 
         # Extract API key from headers

data/lib/vector_mcp/security/strategies/custom.rb

@@ -17,13 +17,16 @@ module VectorMCP
         end
 
         # Authenticate a request using the custom handler.
+        # The handler receives a {VectorMCP::RequestContext}, which supports
+        # hash-style access (`request[:headers]`, `request[:params]`) for
+        # compatibility with handlers written against the legacy request hash.
         # If the handler returns a Hash with a :user key, the value is extracted
         # so that AuthManager receives the user data directly.
-        # @param request [Hash] the request object
+        # @param request [VectorMCP::RequestContext, Hash] the request
         # @return [Object, nil, false] user data or false if authentication failed.
         #   A return of nil (from { user: nil }) signals "authenticated, no user object."
         def authenticate(request)
-          result = @handler.call(request)
+          result = @handler.call(VectorMCP::RequestContext.coerce(request))
           return false unless result && result != false
 
           return result unless result.is_a?(Hash) && result.key?(:user)

data/lib/vector_mcp/security/strategies/jwt_token.rb

@@ -35,10 +35,10 @@ module VectorMCP
         end
 
         # Authenticate a request using JWT token
-        # @param request [Hash] the request object
+        # @param request [VectorMCP::RequestContext, Hash] the request
         # @return [Hash, false] decoded JWT payload or false if authentication failed
         def authenticate(request)
-          token = extract_token(request)
+          token = extract_token(VectorMCP::RequestContext.coerce(request))
           return false unless token
 
           begin
@@ -70,19 +70,18 @@ module VectorMCP
 
         private
 
-        # Extract JWT token from request
-        # @param request [Hash] the request object
+        # Extract JWT token from the request context
+        # @param request [VectorMCP::RequestContext] the request context
         # @return [String, nil] the extracted token
         def extract_token(request)
-          headers = request[:headers] || request["headers"] || {}
+          headers = request.headers
 
           from_headers = extract_from_auth_header(headers) || extract_from_jwt_header(headers)
           return from_headers if from_headers
 
           return nil unless @allow_query_params
 
-          params = request[:params] || request["params"] || {}
-          extract_from_params(params)
+          extract_from_params(request.params)
         end
 
         # Extract token from Authorization header

data/lib/vector_mcp/server/message_handling.rb

@@ -10,12 +10,14 @@ module VectorMCP
       # This is the main dispatch point for messages received by a transport.
       #
       # @param message [Hash] The parsed JSON-RPC message object.
-      # @param session [VectorMCP::Session] The client session associated with this message.
-      # @param session_id [String] A unique identifier for the underlying transport connection.
+      # @param session [VectorMCP::Session, VectorMCP::Invocation] The session (or per-request
+      #   invocation view of it) this message belongs to.
+      # @param session_id [String, nil] Deprecated: defaults to session.id; used only for log prefixes.
       # @return [Object, nil] For requests, returns the result data to be sent in the JSON-RPC response.
       #   For notifications, returns `nil`.
       # @raise [VectorMCP::ProtocolError] if the message is invalid or an error occurs during handling.
-      def handle_message(message, session, session_id)
+      def handle_message(message, session, session_id = nil)
+        session_id ||= session.id
         id = message["id"]
         method = message["method"]
         params = message["params"] || {}
@@ -83,8 +85,6 @@ module VectorMCP
       end
 
       # Validates that the session is properly initialized for the given request.
-      # Transports are contractually required to pass a VectorMCP::Session here —
-      # never the SessionManager wrapper struct.
       # @api private
       def validate_session_initialization(id, method, _params, session)
         return if session.initialized?

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/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/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,24 +54,21 @@ module VectorMCP
           end
         end
 
-        # Initializes a new HTTP stream session manager.
-        #
-        # @param transport [HttpStream] The parent transport instance
-        # @param session_timeout [Integer] Session timeout in seconds
-
         # 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.
+        #
+        # @return [VectorMCP::Session] The newly created session
         def create_session(session_id = nil, rack_env = nil)
           session_id ||= generate_session_id
-          now = Time.now
 
           request_context = VectorMCP::RequestContext.from_rack_env(rack_env, "http_stream")
-          session_context = VectorMCP::Session.new(
+          session = VectorMCP::Session.new(
             @transport.server, @transport, id: session_id, request_context: request_context
           )
+          session.extend(SessionStreaming)
+          session.metadata.merge!(create_session_metadata)
 
-          session = Session.new(session_id, session_context, now, now, create_session_metadata)
           @sessions[session_id] = session
 
           logger.info { "Session created: #{session_id}" }
@@ -90,25 +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
 
         # 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

data/lib/vector_mcp/transport/http_stream.rb

@@ -384,20 +384,17 @@ module VectorMCP
       end
 
       # Runs the configured authentication strategy against the Rack env and returns
-      # the resulting SessionContext. The request is normalized into the
-      # +{ headers:, params:, method:, path:, rack_env: }+ hash shape that the rest
-      # of the codebase's authentication pipeline uses (see
-      # +VectorMCP::Handlers::Core.extract_request_from_session+), so +:custom+
-      # strategy handlers see the same contract here as they do on the in-handler
-      # auth path. Errors in the strategy are logged and treated as unauthenticated
-      # rather than propagated, so a malformed token can never crash the request
-      # pipeline.
+      # the resulting SessionContext. The request is carried as a
+      # {VectorMCP::RequestContext} — the same type the in-handler auth path uses —
+      # so +:custom+ strategy handlers see one contract everywhere. Errors in the
+      # strategy are logged and treated as unauthenticated rather than propagated,
+      # so a malformed token can never crash the request pipeline.
       #
       # @param env [Hash] The Rack environment
       # @return [VectorMCP::Security::SessionContext]
       def authenticate_transport_request(env)
-        normalized_request = @server.security_middleware.normalize_request(env)
-        @server.security_middleware.authenticate_request(normalized_request)
+        request_context = VectorMCP::RequestContext.from_rack_env(env, "http_stream")
+        @server.security_middleware.authenticate_request(request_context)
       rescue StandardError => e
         VectorMCP.logger_for("security").warn do
           "OAuth transport auth strategy raised #{e.class}: #{e.message}"
@@ -477,24 +474,35 @@ module VectorMCP
           return [202, { "Mcp-Session-Id" => session.id }, []]
         end
 
+        # Each request is dispatched through its own Invocation so that
+        # request-scoped state (headers, params, resolved auth) never leaks
+        # between concurrent requests on the same session.
+        invocation = VectorMCP::Invocation.new(
+          session,
+          request_context: VectorMCP::RequestContext.from_rack_env(env, "http_stream")
+        )
+
         # Notifications: has method, no id -> 202 Accepted with no body (MCP spec requirement)
         if message["method"] && !message.key?("id")
-          @server.handle_message(message, session.context, session.id)
+          @server.handle_message(message, invocation)
           return [202, { "Mcp-Session-Id" => session.id }, []]
         end
 
-        result = @server.handle_message(message, session.context, session.id)
+        result = @server.handle_message(message, invocation)
         build_rpc_response(env, result, message["id"], session.id)
       rescue VectorMCP::ProtocolError => e
         build_protocol_error_response(env, e, session_id: session.id)
       end
 
       # Resolves or creates the session for a POST request following MCP spec rules:
-      # - session_id present and known  → return existing session (updating request context)
+      # - session_id present and known  → return existing session
       # - session_id present but unknown/expired → 404 Not Found
       # - no session_id + initialize request → create new session
       # - no session_id + other request → 400 Bad Request
       #
+      # Request-scoped data is NOT written to the session here; each request
+      # carries its own context via the Invocation built at dispatch time.
+      #
       # @param session_id [String, nil] Client-supplied Mcp-Session-Id header value
       # @param message [Hash] Parsed JSON-RPC message
       # @param env [Hash] Rack environment
@@ -503,14 +511,7 @@ module VectorMCP
         is_initialize = message.is_a?(Hash) && message["method"] == "initialize"
 
         if session_id
-          session = @session_manager.get_session(session_id)
-          return not_found_response("Unknown or expired session") unless session
-
-          if env
-            request_context = VectorMCP::RequestContext.from_rack_env(env, "http_stream")
-            session.context.request_context = request_context
-          end
-          session
+          @session_manager.get_session(session_id) || not_found_response("Unknown or expired session")
         elsif is_initialize
           @session_manager.create_session(nil, env)
         else
@@ -1055,7 +1056,7 @@ module VectorMCP
 
       # Finds the first session with an active streaming connection.
       #
-      # @return [SessionManager::Session, nil] The first streaming session or nil if none found
+      # @return [VectorMCP::Session, nil] The first streaming session or nil if none found
       def find_streaming_session
         @session_manager.active_session_ids.each do |session_id|
           session = @session_manager.get_session(session_id)
@@ -1066,7 +1067,7 @@ module VectorMCP
 
       # Finds the first available session (streaming or non-streaming).
       #
-      # @return [SessionManager::Session, nil] The first available session or nil if none found
+      # @return [VectorMCP::Session, nil] The first available session or nil if none found
       def find_first_session
         session_ids = @session_manager.active_session_ids
         return nil if session_ids.empty?

data/lib/vector_mcp/version.rb

@@ -2,5 +2,5 @@
 
 module VectorMCP
   # The current version of the VectorMCP gem.
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/vector_mcp.rb

@@ -7,6 +7,7 @@ require_relative "vector_mcp/version"
 require_relative "vector_mcp/errors"
 require_relative "vector_mcp/definitions"
 require_relative "vector_mcp/session"
+require_relative "vector_mcp/invocation"
 require_relative "vector_mcp/util"
 require_relative "vector_mcp/util/token_sweeper"
 require_relative "vector_mcp/token_store"
@@ -61,6 +62,14 @@ module VectorMCP
       @logger ||= Logger.for("vectormcp")
     end
 
+    # Emit a deprecation warning. Centralized so tests and applications can
+    # intercept or silence deprecations in one place.
+    # @param message [String] description of the deprecated usage and its replacement
+    # @return [void]
+    def deprecation_warning(message)
+      warn("[DEPRECATION] VectorMCP: #{message}")
+    end
+
     # Creates a new {VectorMCP::Server} instance. This is a **thin wrapper** around
     # `VectorMCP::Server.new`; it exists purely for syntactic sugar so you can write
     # `VectorMCP.new` instead of `VectorMCP::Server.new`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vector_mcp
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Sergio Bayona
@@ -129,6 +129,7 @@ files:
 - lib/vector_mcp/errors.rb
 - lib/vector_mcp/handlers/core.rb
 - lib/vector_mcp/image_util.rb
+- lib/vector_mcp/invocation.rb
 - lib/vector_mcp/log_filter.rb
 - lib/vector_mcp/logger.rb
 - lib/vector_mcp/middleware.rb