vector_mcp 0.3.0 → 0.3.2

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Security
+    module Strategies
+      # Custom authentication strategy
+      # Allows developers to implement their own authentication logic
+      class Custom
+        attr_reader :handler
+
+        # Initialize with a custom authentication handler
+        # @param handler [Proc] a block that takes a request and returns user info or false
+        def initialize(&handler)
+          raise ArgumentError, "Custom authentication strategy requires a block" unless handler
+
+          @handler = handler
+        end
+
+        # Authenticate a request using the custom handler
+        # @param request [Hash] the request object
+        # @return [Object, false] result from custom handler or false if authentication failed
+        def authenticate(request)
+          result = @handler.call(request)
+
+          # Ensure result includes strategy info if it's successful
+          if result && result != false
+            format_successful_result(result)
+          else
+            false
+          end
+        rescue NoMemoryError, StandardError
+          # Log error but return false for security
+          false
+        end
+
+        # Check if handler is configured
+        # @return [Boolean] true if handler is present
+        def configured?
+          !@handler.nil?
+        end
+
+        private
+
+        # Format successful authentication result with strategy metadata
+        # @param result [Object] the result from the custom handler
+        # @return [Object] formatted result with strategy metadata
+        def format_successful_result(result)
+          case result
+          when Hash
+            # If result has a :user key, extract it and use as main user data
+            if result.key?(:user)
+              user_data = result[:user]
+              # For nil user, return a marker that will become nil in session context
+              return :authenticated_nil_user if user_data.nil?
+
+              user_data
+            else
+              result.merge(strategy: "custom", authenticated_at: Time.now)
+            end
+          else
+            {
+              user: result,
+              strategy: "custom",
+              authenticated_at: Time.now
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+begin
+  require "jwt"
+rescue LoadError
+  # JWT gem is optional - will raise error when trying to use JWT strategy
+end
+
+module VectorMCP
+  module Security
+    module Strategies
+      # JWT Token authentication strategy
+      # Provides stateless authentication using JSON Web Tokens
+      class JwtToken
+        attr_reader :secret, :algorithm, :options
+
+        # Initialize JWT strategy
+        # @param secret [String] the secret key for JWT verification
+        # @param algorithm [String] the JWT algorithm (default: HS256)
+        # @param options [Hash] additional JWT verification options
+        def initialize(secret:, algorithm: "HS256", **options)
+          raise LoadError, "JWT gem is required for JWT authentication strategy" unless defined?(JWT)
+
+          @secret = secret
+          @algorithm = algorithm
+          @options = {
+            algorithm: @algorithm,
+            verify_expiration: true,
+            verify_iat: true,
+            verify_iss: false,
+            verify_aud: false
+          }.merge(options)
+        end
+
+        # Authenticate a request using JWT token
+        # @param request [Hash] the request object
+        # @return [Hash, false] decoded JWT payload or false if authentication failed
+        def authenticate(request)
+          token = extract_token(request)
+          return false unless token
+
+          begin
+            decoded = JWT.decode(token, @secret, true, @options)
+            payload = decoded[0] # First element is the payload
+            headers = decoded[1] # Second element is the headers
+
+            # Return user info from JWT payload
+            {
+              **payload,
+              strategy: "jwt",
+              authenticated_at: Time.now,
+              jwt_headers: headers
+            }
+          rescue JWT::ExpiredSignature, JWT::InvalidIssuerError, JWT::InvalidAudienceError,
+                 JWT::VerificationError, JWT::DecodeError, StandardError
+            false # Token validation failed
+          end
+        end
+
+        # Generate a JWT token (utility method for testing/development)
+        # @param payload [Hash] the payload to encode
+        # @param expires_in [Integer] expiration time in seconds from now
+        # @return [String] the generated JWT token
+        def generate_token(payload, expires_in: 3600)
+          exp_payload = payload.merge(
+            exp: Time.now.to_i + expires_in,
+            iat: Time.now.to_i
+          )
+          JWT.encode(exp_payload, @secret, @algorithm)
+        end
+
+        # Check if JWT gem is available
+        # @return [Boolean] true if JWT gem is loaded
+        def self.available?
+          defined?(JWT)
+        end
+
+        private
+
+        # Extract JWT token from request
+        # @param request [Hash] the request object
+        # @return [String, nil] the extracted token
+        def extract_token(request)
+          headers = request[:headers] || request["headers"] || {}
+          params = request[:params] || request["params"] || {}
+
+          extract_from_auth_header(headers) ||
+            extract_from_jwt_header(headers) ||
+            extract_from_params(params)
+        end
+
+        # Extract token from Authorization header
+        # @param headers [Hash] request headers
+        # @return [String, nil] the token if found
+        def extract_from_auth_header(headers)
+          auth_header = headers["Authorization"] || headers["authorization"]
+          return nil unless auth_header&.start_with?("Bearer ")
+
+          token = auth_header[7..] # Remove 'Bearer ' prefix
+          return nil if token.nil? || token.strip.empty?
+
+          token.strip
+        end
+
+        # Extract token from custom JWT header
+        # @param headers [Hash] request headers
+        # @return [String, nil] the token if found
+        def extract_from_jwt_header(headers)
+          headers["X-JWT-Token"] || headers["x-jwt-token"]
+        end
+
+        # Extract token from query parameters
+        # @param params [Hash] request parameters
+        # @return [String, nil] the token if found
+        def extract_from_params(params)
+          params["jwt_token"] || params["token"]
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/security.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Security namespace for VectorMCP
+# Contains authentication, authorization, and security middleware components
+
+require_relative "security/auth_manager"
+require_relative "security/authorization"
+require_relative "security/middleware"
+require_relative "security/session_context"
+require_relative "security/strategies/api_key"
+require_relative "security/strategies/jwt_token"
+require_relative "security/strategies/custom"
+
+module VectorMCP
+  # Security components for VectorMCP servers
+  # Provides opt-in authentication and authorization
+  module Security
+    # Get default authentication manager
+    # @return [AuthManager] a new authentication manager instance
+    def self.auth_manager
+      AuthManager.new
+    end
+
+    # Get default authorization manager
+    # @return [Authorization] a new authorization manager instance
+    def self.authorization
+      Authorization.new
+    end
+
+    # Create security middleware with default components
+    # @param auth_manager [AuthManager] optional custom auth manager
+    # @param authorization [Authorization] optional custom authorization
+    # @return [Middleware] configured security middleware
+    def self.middleware(auth_manager: nil, authorization: nil)
+      auth_manager ||= self.auth_manager
+      authorization ||= self.authorization
+      Middleware.new(auth_manager, authorization)
+    end
+
+    # Check if JWT support is available
+    # @return [Boolean] true if JWT gem is loaded
+    def self.jwt_available?
+      Strategies::JwtToken.available?
+    end
+  end
+end

data/lib/vector_mcp/server.rb

@@ -12,6 +12,14 @@ require_relative "util" # Needed if not using Handlers::Core
 require_relative "server/registry"
 require_relative "server/capabilities"
 require_relative "server/message_handling"
+require_relative "security/auth_manager"
+require_relative "security/authorization"
+require_relative "security/middleware"
+require_relative "security/session_context"
+require_relative "security/strategies/api_key"
+require_relative "security/strategies/jwt_token"
+require_relative "security/strategies/custom"
+require_relative "middleware"
 
 module VectorMCP
   # The `Server` class is the central component for an MCP server implementation.
@@ -62,7 +70,8 @@ module VectorMCP
     # The specific version of the Model Context Protocol this server implements.
     PROTOCOL_VERSION = "2024-11-05"
 
-    attr_reader :logger, :name, :version, :protocol_version, :tools, :resources, :prompts, :roots, :in_flight_requests
+    attr_reader :logger, :name, :version, :protocol_version, :tools, :resources, :prompts, :roots, :in_flight_requests,
+                :auth_manager, :authorization, :security_middleware, :middleware_manager
     attr_accessor :transport
 
     # Initializes a new VectorMCP server.
@@ -90,8 +99,8 @@ module VectorMCP
       @name = name_pos || name || "UnnamedServer"
       @version = version
       @protocol_version = options[:protocol_version] || PROTOCOL_VERSION
-      @logger = VectorMCP.logger
-      @logger.level = options[:log_level] if options[:log_level]
+      @logger = VectorMCP.logger_for("server")
+      # NOTE: log level should be configured via VectorMCP.configure_logging instead
 
       @transport = nil
       @tools = {}
@@ -108,6 +117,14 @@ module VectorMCP
       # Configure sampling capabilities
       @sampling_config = configure_sampling_capabilities(options[:sampling_config] || {})
 
+      # Initialize security components
+      @auth_manager = Security::AuthManager.new
+      @authorization = Security::Authorization.new
+      @security_middleware = Security::Middleware.new(@auth_manager, @authorization)
+
+      # Initialize middleware manager
+      @middleware_manager = Middleware::Manager.new
+
       setup_default_handlers
 
       @logger.info("Server instance '#{@name}' v#{@version} (MCP Protocol: #{@protocol_version}, Gem: v#{VectorMCP::VERSION}) initialized.")
@@ -120,7 +137,7 @@ module VectorMCP
     # @param transport [:stdio, :sse, VectorMCP::Transport::Base] The transport to use.
     #   Can be a symbol (`:stdio`, `:sse`) or an initialized transport instance.
     #   If a symbol is provided, the method will instantiate the corresponding transport class.
-    #   If `:sse` is chosen, ensure `async` and `falcon` gems are available.
+    #   If `:sse` is chosen, it uses Puma as the HTTP server.
     # @param options [Hash] Transport-specific options (e.g., `:host`, `:port` for SSE).
     #   These are passed to the transport's constructor if a symbol is provided for `transport`.
     # @return [void]
@@ -135,7 +152,7 @@ module VectorMCP
                              require_relative "transport/sse"
                              VectorMCP::Transport::SSE.new(self, **options)
                            rescue LoadError => e
-                             logger.fatal("SSE transport requires additional dependencies. Install the 'async' and 'falcon' gems.")
+                             logger.fatal("SSE transport requires additional dependencies.")
                              raise NotImplementedError, "SSE transport dependencies not available: #{e.message}"
                            end
                          when VectorMCP::Transport::Base # Allow passing an initialized transport instance
@@ -148,6 +165,173 @@ module VectorMCP
       self.transport = active_transport
       active_transport.run
     end
+
+    # --- Security Configuration ---
+
+    # Enable authentication with specified strategy and configuration
+    # @param strategy [Symbol] the authentication strategy (:api_key, :jwt, :custom)
+    # @param options [Hash] strategy-specific configuration options
+    # @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?
+
+      @auth_manager.enable!(default_strategy: strategy)
+
+      case strategy
+      when :api_key
+        add_api_key_auth(options[:keys] || [])
+      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
+
+      @logger.info("Authentication enabled with strategy: #{strategy}")
+    end
+
+    # Disable authentication (return to pass-through mode)
+    # @return [void]
+    def disable_authentication!
+      @auth_manager.disable!
+      @logger.info("Authentication disabled")
+    end
+
+    # Enable authorization with optional policy configuration block
+    # @param block [Proc] optional block for configuring authorization policies
+    # @return [void]
+    def enable_authorization!(&block)
+      @authorization.enable!
+      instance_eval(&block) if block_given?
+      @logger.info("Authorization enabled")
+    end
+
+    # Disable authorization (return to pass-through mode)
+    # @return [void]
+    def disable_authorization!
+      @authorization.disable!
+      @logger.info("Authorization disabled")
+    end
+
+    # Add authorization policy for tools
+    # @param block [Proc] policy block that receives (user, action, tool)
+    # @return [void]
+    def authorize_tools(&block)
+      @authorization.add_policy(:tool, &block)
+    end
+
+    # Add authorization policy for resources
+    # @param block [Proc] policy block that receives (user, action, resource)
+    # @return [void]
+    def authorize_resources(&block)
+      @authorization.add_policy(:resource, &block)
+    end
+
+    # Add authorization policy for prompts
+    # @param block [Proc] policy block that receives (user, action, prompt)
+    # @return [void]
+    def authorize_prompts(&block)
+      @authorization.add_policy(:prompt, &block)
+    end
+
+    # Add authorization policy for roots
+    # @param block [Proc] policy block that receives (user, action, root)
+    # @return [void]
+    def authorize_roots(&block)
+      @authorization.add_policy(:root, &block)
+    end
+
+    # Check if security features are enabled
+    # @return [Boolean] true if authentication or authorization is enabled
+    def security_enabled?
+      @security_middleware.security_enabled?
+    end
+
+    # Get current security status for debugging/monitoring
+    # @return [Hash] security configuration status
+    def security_status
+      @security_middleware.security_status
+    end
+
+    # --- Middleware Management ---
+
+    # Register middleware for specific hook types
+    # @param middleware_class [Class] Middleware class inheriting from VectorMCP::Middleware::Base
+    # @param hooks [Symbol, Array<Symbol>] Hook types to register for (e.g., :before_tool_call, [:before_tool_call, :after_tool_call])
+    # @param priority [Integer] Execution priority (lower numbers execute first, default: 100)
+    # @param conditions [Hash] Conditions for when middleware should run
+    # @option conditions [Array<String>] :only_operations Only run for these operations
+    # @option conditions [Array<String>] :except_operations Don't run for these operations
+    # @option conditions [Array<String>] :only_users Only run for these user IDs
+    # @option conditions [Array<String>] :except_users Don't run for these user IDs
+    # @option conditions [Boolean] :critical If true, errors in this middleware stop execution
+    # @example
+    #   server.use_middleware(MyMiddleware, :before_tool_call)
+    #   server.use_middleware(AuthMiddleware, [:before_request, :after_response], priority: 10)
+    #   server.use_middleware(LoggingMiddleware, :after_tool_call, conditions: { only_operations: ['important_tool'] })
+    def use_middleware(middleware_class, hooks, priority: Middleware::Hook::DEFAULT_PRIORITY, conditions: {})
+      @middleware_manager.register(middleware_class, hooks, priority: priority, conditions: conditions)
+      @logger.info("Registered middleware: #{middleware_class.name}")
+    end
+
+    # Remove all middleware hooks for a specific class
+    # @param middleware_class [Class] Middleware class to remove
+    def remove_middleware(middleware_class)
+      @middleware_manager.unregister(middleware_class)
+      @logger.info("Removed middleware: #{middleware_class.name}")
+    end
+
+    # Get middleware statistics
+    # @return [Hash] Statistics about registered middleware
+    def middleware_stats
+      @middleware_manager.stats
+    end
+
+    # Clear all middleware (useful for testing)
+    def clear_middleware!
+      @middleware_manager.clear!
+      @logger.info("Cleared all middleware")
+    end
+
+    private
+
+    # Add API key authentication strategy
+    # @param keys [Array<String>] array of valid API keys
+    # @return [void]
+    def add_api_key_auth(keys)
+      strategy = Security::Strategies::ApiKey.new(keys: keys)
+      @auth_manager.add_strategy(:api_key, strategy)
+    end
+
+    # Add JWT authentication strategy
+    # @param options [Hash] JWT configuration options
+    # @return [void]
+    def add_jwt_auth(options)
+      strategy = Security::Strategies::JwtToken.new(**options)
+      @auth_manager.add_strategy(:jwt, strategy)
+    end
+
+    # Add custom authentication strategy
+    # @param handler [Proc] custom authentication handler block
+    # @return [void]
+    def add_custom_auth(&block)
+      strategy = Security::Strategies::Custom.new(&block)
+      @auth_manager.add_strategy(:custom, strategy)
+    end
+
+    # Clear all authentication strategies
+    # @return [void]
+    def clear_auth_strategies
+      @auth_manager.strategies.each_key do |strategy_name|
+        @auth_manager.remove_strategy(strategy_name)
+      end
+    end
   end
 
   module Transport

data/lib/vector_mcp/session.rb

@@ -95,10 +95,43 @@ module VectorMCP
     def sample(request_params, timeout: nil)
       validate_sampling_preconditions
 
-      sampling_req_obj = VectorMCP::Sampling::Request.new(request_params)
-      @logger.info("[Session #{@id}] Sending sampling/createMessage request to client.")
-
-      send_sampling_request(sampling_req_obj, timeout)
+      # Create middleware context for sampling
+      context = VectorMCP::Middleware::Context.new(
+        operation_type: :sampling,
+        operation_name: "createMessage",
+        params: request_params,
+        session: self,
+        server: @server,
+        metadata: { start_time: Time.now, timeout: timeout }
+      )
+
+      # Execute before_sampling_request hooks
+      context = @server.middleware_manager.execute_hooks(:before_sampling_request, context)
+      raise context.error if context.error?
+
+      begin
+        sampling_req_obj = VectorMCP::Sampling::Request.new(request_params)
+        @logger.info("[Session #{@id}] Sending sampling/createMessage request to client.")
+
+        result = send_sampling_request(sampling_req_obj, timeout)
+
+        # Set result in context
+        context.result = result
+
+        # Execute after_sampling_response hooks
+        context = @server.middleware_manager.execute_hooks(:after_sampling_response, context)
+
+        context.result
+      rescue StandardError => e
+        # Set error in context and execute error hooks
+        context.error = e
+        context = @server.middleware_manager.execute_hooks(:on_sampling_error, context)
+
+        # Re-raise unless middleware handled the error
+        raise e unless context.result
+
+        context.result
+      end
     end
 
     private

data/lib/vector_mcp/version.rb

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

data/lib/vector_mcp.rb

@@ -11,14 +11,16 @@ require_relative "vector_mcp/util"
 require_relative "vector_mcp/image_util"
 require_relative "vector_mcp/handlers/core"
 require_relative "vector_mcp/transport/stdio"
-# require_relative "vector_mcp/transport/sse" # Load on demand to avoid async dependencies
+# require_relative "vector_mcp/transport/sse" # Load on demand
+require_relative "vector_mcp/logger"
+require_relative "vector_mcp/middleware"
 require_relative "vector_mcp/server"
 
 # The VectorMCP module provides a full-featured, opinionated Ruby implementation
 # of the **Model Context Protocol (MCP)**.  It gives developers everything needed
 # to spin up an MCP-compatible server—including:
 #
-# * **Transport adapters** (synchronous `stdio` or asynchronous HTTP + SSE)
+# * **Transport adapters** (synchronous `stdio` or HTTP + SSE)
 # * **High-level abstractions** for *tools*, *resources*, and *prompts*
 # * **JSON-RPC 2.0** message handling with sensible defaults and detailed
 #   error reporting helpers
@@ -44,13 +46,19 @@ require_relative "vector_mcp/server"
 # order to serve multiple concurrent clients over HTTP.
 #
 module VectorMCP
-  # @return [Logger] the shared logger instance for the library.
-  @logger = Logger.new($stderr, level: Logger::INFO, progname: "VectorMCP")
-
   class << self
-    # @!attribute [r] logger
-    #   @return [Logger] the shared logger instance for the library.
-    attr_reader :logger
+    # Get a component-specific logger
+    # @param component [String, Symbol] the component name
+    # @return [VectorMCP::Logger] component logger
+    def logger_for(component)
+      Logger.for(component)
+    end
+
+    # Get the default logger
+    # @return [VectorMCP::Logger] default logger
+    def logger
+      @logger ||= Logger.for("vectormcp")
+    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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vector_mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Sergio Bayona
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
@@ -79,8 +93,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.4'
-description: Server-side tools for implementing the Model Context Protocol in Ruby
-  applications
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby gem implementing the Model Context Protocol (MCP) server-side
+  specification. Provides a framework for creating MCP servers that expose tools,
+  resources, prompts, and roots to LLM clients with comprehensive security features,
+  structured logging, and production-ready capabilities.
 email:
 - bayona.sergio@gmail.com
 executables:
@@ -89,6 +119,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - bin/console
@@ -98,8 +129,22 @@ files:
 - lib/vector_mcp/errors.rb
 - lib/vector_mcp/handlers/core.rb
 - lib/vector_mcp/image_util.rb
+- lib/vector_mcp/logger.rb
+- lib/vector_mcp/middleware.rb
+- lib/vector_mcp/middleware/base.rb
+- lib/vector_mcp/middleware/context.rb
+- lib/vector_mcp/middleware/hook.rb
+- lib/vector_mcp/middleware/manager.rb
 - lib/vector_mcp/sampling/request.rb
 - lib/vector_mcp/sampling/result.rb
+- lib/vector_mcp/security.rb
+- lib/vector_mcp/security/auth_manager.rb
+- lib/vector_mcp/security/authorization.rb
+- lib/vector_mcp/security/middleware.rb
+- lib/vector_mcp/security/session_context.rb
+- lib/vector_mcp/security/strategies/api_key.rb
+- lib/vector_mcp/security/strategies/custom.rb
+- lib/vector_mcp/security/strategies/jwt_token.rb
 - lib/vector_mcp/server.rb
 - lib/vector_mcp/server/capabilities.rb
 - lib/vector_mcp/server/message_handling.rb
@@ -128,7 +173,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.0.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="