vector_mcp 0.2.0 → 0.3.1

data/lib/vector_mcp/security/session_context.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Security
+    # Represents the security context for a user session
+    # Contains authentication and authorization information
+    class SessionContext
+      attr_reader :user, :authenticated, :permissions, :auth_strategy, :authenticated_at
+
+      # Initialize session context
+      # @param user [Object] the authenticated user object
+      # @param authenticated [Boolean] whether the user is authenticated
+      # @param auth_strategy [String] the authentication strategy used
+      # @param authenticated_at [Time] when authentication occurred
+      def initialize(user: nil, authenticated: false, auth_strategy: nil, authenticated_at: nil)
+        @user = user
+        @authenticated = authenticated
+        @auth_strategy = auth_strategy
+        @authenticated_at = authenticated_at || Time.now
+        @permissions = Set.new
+      end
+
+      # Check if the session is authenticated
+      # @return [Boolean] true if authenticated
+      def authenticated?
+        @authenticated
+      end
+
+      # Check if the user has a specific permission
+      # @param permission [String, Symbol] the permission to check
+      # @return [Boolean] true if user has the permission
+      def can?(permission)
+        @permissions.include?(permission.to_s)
+      end
+
+      # Check if the user can perform an action on a resource
+      # @param action [String, Symbol] the action (e.g., 'read', 'write', 'execute')
+      # @param resource [String, Symbol] the resource (e.g., 'tools', 'resources')
+      # @return [Boolean] true if user can perform the action
+      def can_access?(action, resource)
+        can?("#{action}:#{resource}") || can?("#{action}:*") || can?("*:#{resource}") || can?("*:*")
+      end
+
+      # Add a permission to the session
+      # @param permission [String, Symbol] the permission to add
+      def add_permission(permission)
+        @permissions << permission.to_s
+      end
+
+      # Add multiple permissions to the session
+      # @param permissions [Array<String, Symbol>] the permissions to add
+      def add_permissions(permissions)
+        permissions.each { |perm| add_permission(perm) }
+      end
+
+      # Remove a permission from the session
+      # @param permission [String, Symbol] the permission to remove
+      def remove_permission(permission)
+        @permissions.delete(permission.to_s)
+      end
+
+      # Clear all permissions
+      def clear_permissions
+        @permissions.clear
+      end
+
+      # Get user identifier for logging/auditing
+      # @return [String] a string identifying the user
+      def user_identifier
+        return "anonymous" unless authenticated?
+        return "anonymous" if @user.nil?
+
+        case @user
+        when Hash
+          @user[:user_id] || @user[:sub] || @user[:email] || @user[:api_key] || "authenticated_user"
+        when String
+          @user
+        else
+          @user.respond_to?(:id) ? @user.id.to_s : "authenticated_user"
+        end
+      end
+
+      # Get authentication method used
+      # @return [String] the authentication strategy
+      def auth_method
+        @auth_strategy || "none"
+      end
+
+      # Check if authentication is recent (within specified seconds)
+      # @param max_age [Integer] maximum age in seconds (default: 3600 = 1 hour)
+      # @return [Boolean] true if authentication is recent
+      def auth_recent?(max_age: 3600)
+        return false unless authenticated?
+
+        (Time.now - @authenticated_at) <= max_age
+      end
+
+      # Convert to hash for serialization
+      # @return [Hash] session context as hash
+      def to_h
+        {
+          authenticated: @authenticated,
+          user_identifier: user_identifier,
+          auth_strategy: @auth_strategy,
+          authenticated_at: @authenticated_at&.iso8601,
+          permissions: @permissions.to_a
+        }
+      end
+
+      # Create an anonymous (unauthenticated) session context
+      # @return [SessionContext] an unauthenticated session
+      def self.anonymous
+        new(authenticated: false)
+      end
+
+      # Create an authenticated session context from auth result
+      # @param auth_result [Hash] the authentication result
+      # @return [SessionContext] an authenticated session
+      def self.from_auth_result(auth_result)
+        return anonymous unless auth_result&.dig(:authenticated)
+
+        user_data = auth_result[:user]
+
+        # Handle special marker for authenticated nil user
+        if user_data == :authenticated_nil_user
+          new(
+            user: nil,
+            authenticated: true,
+            auth_strategy: "custom",
+            authenticated_at: Time.now
+          )
+        else
+          # Extract strategy and authenticated_at only if user_data is a Hash
+          strategy = user_data.is_a?(Hash) ? user_data[:strategy] : nil
+          auth_time = user_data.is_a?(Hash) ? user_data[:authenticated_at] : nil
+
+          new(
+            user: user_data,
+            authenticated: true,
+            auth_strategy: strategy,
+            authenticated_at: auth_time
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Security
+    module Strategies
+      # API Key authentication strategy
+      # Supports multiple key formats and storage methods
+      class ApiKey
+        attr_reader :valid_keys
+
+        # Initialize with a list of valid API keys
+        # @param keys [Array<String>] array of valid API keys
+        def initialize(keys: [])
+          @valid_keys = Set.new(keys.map(&:to_s))
+        end
+
+        # Add a valid API key
+        # @param key [String] the API key to add
+        def add_key(key)
+          @valid_keys << key.to_s
+        end
+
+        # Remove an API key
+        # @param key [String] the API key to remove
+        def remove_key(key)
+          @valid_keys.delete(key.to_s)
+        end
+
+        # Authenticate a request using API key
+        # @param request [Hash] the request object
+        # @return [Hash, false] user info hash or false if authentication failed
+        def authenticate(request)
+          api_key = extract_api_key(request)
+          return false unless api_key&.length&.positive?
+
+          if @valid_keys.include?(api_key)
+            {
+              api_key: api_key,
+              strategy: "api_key",
+              authenticated_at: Time.now
+            }
+          else
+            false
+          end
+        end
+
+        # Check if any keys are configured
+        # @return [Boolean] true if keys are available
+        def configured?
+          !@valid_keys.empty?
+        end
+
+        # Get count of configured keys (for debugging)
+        # @return [Integer] number of configured keys
+        def key_count
+          @valid_keys.size
+        end
+
+        private
+
+        # Extract API key from various request formats
+        # @param request [Hash] the request object
+        # @return [String, nil] the extracted API key
+        def extract_api_key(request)
+          headers = normalize_headers(request)
+          params = normalize_params(request)
+
+          extract_from_headers(headers) || 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)
+          headers = {}
+          env.each do |key, value|
+            next unless key.start_with?("HTTP_")
+
+            # Convert HTTP_X_API_KEY to X-API-Key format
+            header_name = key[5..].split("_").map do |part|
+              case part.upcase
+              when "API" then "API" # Keep API in all caps
+              else part.capitalize
+              end
+            end.join("-")
+            headers[header_name] = value
+          end
+
+          # Add special headers
+          headers["Authorization"] = env["HTTP_AUTHORIZATION"] if env["HTTP_AUTHORIZATION"]
+          headers["Content-Type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
+          headers
+        end
+
+        # Extract params from Rack environment
+        # @param env [Hash] the Rack environment
+        # @return [Hash] normalized params
+        def extract_params_from_rack_env(env)
+          params = {}
+          if env["QUERY_STRING"]
+            require "uri"
+            params = URI.decode_www_form(env["QUERY_STRING"]).to_h
+          end
+          params
+        end
+
+        # Extract API key from headers
+        # @param headers [Hash] request headers
+        # @return [String, nil] the API key if found
+        def extract_from_headers(headers)
+          # 1. X-API-Key header (most common)
+          api_key = headers["X-API-Key"] || headers["x-api-key"]
+          return api_key if api_key
+
+          # 2. Authorization header
+          extract_from_auth_header(headers["Authorization"] || headers["authorization"])
+        end
+
+        # Extract API key from Authorization header
+        # @param auth_header [String, nil] the authorization header value
+        # @return [String, nil] the API key if found
+        def extract_from_auth_header(auth_header)
+          return nil unless auth_header
+
+          # Bearer token format
+          return auth_header[7..] if auth_header.start_with?("Bearer ")
+
+          # API-Key scheme format
+          return auth_header[8..] if auth_header.start_with?("API-Key ")
+
+          nil
+        end
+
+        # Extract API key from query parameters
+        # @param params [Hash] request parameters
+        # @return [String, nil] the API key if found
+        def extract_from_params(params)
+          params["api_key"] || params["apikey"]
+        end
+      end
+    end
+  end
+end

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,118 @@
+# 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::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 ")
+
+          auth_header[7..] # Remove 'Bearer ' prefix
+        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/registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json-schema"
+
 module VectorMCP
   class Server
     # Handles registration of tools, resources, prompts, and roots
@@ -19,6 +21,9 @@ module VectorMCP
         name_s = name.to_s
         raise ArgumentError, "Tool '#{name_s}' already registered" if @tools[name_s]
 
+        # Validate schema format during registration
+        validate_schema_format!(input_schema) if input_schema
+
         @tools[name_s] = VectorMCP::Definitions::Tool.new(name_s, description, input_schema, handler)
         logger.debug("Registered tool: #{name_s}")
         self
@@ -206,6 +211,25 @@ module VectorMCP
 
       private
 
+      # Validates that the provided schema is a valid JSON Schema.
+      # @api private
+      # @param schema [Hash, nil] The JSON Schema to validate.
+      # @return [void]
+      # @raise [ArgumentError] if the schema is invalid.
+      def validate_schema_format!(schema)
+        return if schema.nil? || schema.empty?
+        return unless schema.is_a?(Hash)
+
+        # Use JSON::Validator to validate the schema format itself
+        validation_errors = JSON::Validator.fully_validate_schema(schema)
+
+        raise ArgumentError, "Invalid input_schema format: #{validation_errors.join("; ")}" unless validation_errors.empty?
+      rescue JSON::Schema::ValidationError => e
+        raise ArgumentError, "Invalid input_schema format: #{e.message}"
+      rescue JSON::Schema::SchemaError => e
+        raise ArgumentError, "Invalid input_schema structure: #{e.message}"
+      end
+
       # Validates the structure of the `arguments` array provided to {#register_prompt}.
       # @api private
       def validate_prompt_arguments(argument_defs)