actionmcp 0.71.1 → 0.80.0

data/lib/action_mcp/gateway_identifier.rb

@@ -1,29 +1,213 @@
 # frozen_string_literal: true
 
 module ActionMCP
+  # Base class for Gateway authentication identifiers.
+  #
+  # Gateway identifiers provide a clean interface for authentication by reading
+  # from request.env keys set by upstream middleware (like Warden, Devise, or custom auth).
+  #
+  # @example Warden/Devise Integration
+  #   class WardenIdentifier < ActionMCP::GatewayIdentifier
+  #     identifier :user
+  #     authenticates :warden
+  #
+  #     def resolve
+  #       # Warden sets 'warden.user' in request.env after authentication
+  #       user = user_from_middleware
+  #       user || raise(Unauthorized, "No authenticated user found")
+  #     end
+  #   end
+  #
+  # @example API Key Authentication
+  #   class ApiKeyIdentifier < ActionMCP::GatewayIdentifier
+  #     identifier :user
+  #     authenticates :api_key
+  #
+  #     def resolve
+  #       # Check for API key in header or query param
+  #       api_key = @request.env['HTTP_X_API_KEY'] ||
+  #                 @request.params['api_key']
+  #       return raise(Unauthorized, "Missing API key") unless api_key
+  #
+  #       user = User.find_by(api_key: api_key)
+  #       user || raise(Unauthorized, "Invalid API key")
+  #     end
+  #   end
+  #
+  # @example Session-based Authentication
+  #   class SessionIdentifier < ActionMCP::GatewayIdentifier
+  #     identifier :user
+  #     authenticates :session
+  #
+  #     def resolve
+  #       user_id = session&.[]('user_id')
+  #       return raise(Unauthorized, "No user session") unless user_id
+  #
+  #       user = User.find_by(id: user_id)
+  #       user || raise(Unauthorized, "Invalid session")
+  #     end
+  #   end
+  #
+  # @example Multi-tenant with Organization
+  #   class TenantIdentifier < ActionMCP::GatewayIdentifier
+  #     identifier :user
+  #     authenticates :tenant
+  #
+  #     def resolve
+  #       # Get user from middleware
+  #       user = user_from_middleware
+  #       return raise(Unauthorized, "No user found") unless user
+  #
+  #       # Check tenant header
+  #       tenant_id = @request.env['HTTP_X_TENANT_ID']
+  #       return raise(Unauthorized, "Missing tenant") unless tenant_id
+  #
+  #       # Verify user has access to tenant
+  #       unless user.tenants.exists?(id: tenant_id)
+  #         raise Unauthorized, "Access denied for tenant"
+  #       end
+  #
+  #       # Set current tenant for the request
+  #       Current.tenant = Tenant.find(tenant_id)
+  #       user
+  #     end
+  #   end
+  #
+  # @example Development/Testing Bypass
+  #   class DevIdentifier < ActionMCP::GatewayIdentifier
+  #     identifier :user
+  #     authenticates :dev
+  #
+  #     def resolve
+  #       return raise(Unauthorized, "Dev auth disabled in production") unless development_env?
+  #
+  #       # Create or find dev user
+  #       User.find_or_create_by!(email: "dev@localhost") do |user|
+  #         user.name = "Development User"
+  #       end
+  #     end
+  #   end
   class GatewayIdentifier
     class Unauthorized < StandardError; end
 
     class << self
-      # e.g. JwtIdentifier.identifier_name => :user
-      attr_reader :identifier_name, :auth_method
+      # @return [Symbol] The name of the identity this identifier provides (e.g., :user, :admin)
+      attr_reader :identifier_name
 
+      # @return [String] The authentication method this identifier handles (e.g., "session", "api_key")
+      attr_reader :auth_method
+
+      # Declares what identity attribute this identifier provides.
+      # This becomes the accessor name on the Gateway instance.
+      #
+      # @param name [Symbol, String] The identity name (e.g., :user, :admin)
+      # @example
+      #   identifier :user
+      #   # Gateway instance will have gateway.user accessor
       def identifier(name)
         @identifier_name = name.to_sym
       end
 
+      # Declares what authentication method this identifier handles.
+      # This should match values in your authentication_methods configuration.
+      #
+      # @param method [Symbol, String] The auth method name (e.g., :session, :api_key)
+      # @example
+      #   authenticates :api_key
+      #   # Matches authentication_methods: ["api_key"] in config
       def authenticates(method)
         @auth_method = method.to_s
       end
     end
 
+    # @param request [ActionDispatch::Request] The request object containing env hash
     def initialize(request)
       @request = request
     end
 
-    # must return a truthy identity object, or raise Unauthorized
+    # Resolves the identity for this authentication method.
+    # Must return a truthy identity object, or raise Unauthorized.
+    #
+    # Common request.env keys set by popular auth middleware:
+    # - 'warden.user' - Warden (used by Devise)
+    # - 'devise.user' - Devise direct
+    # - 'rack.session' - Rack session hash
+    # - 'HTTP_AUTHORIZATION' - Authorization header
+    # - Custom keys set by your middleware
+    #
+    # @return [Object] The authenticated identity (User, Admin, etc.)
+    # @raise [Unauthorized] When authentication fails
+    # @abstract Subclasses must implement this method
     def resolve
       raise NotImplementedError, "#{self.class}#resolve must be implemented"
     end
+
+    protected
+
+    # Helper method to extract Bearer token from Authorization header
+    # @return [String, nil] The token without "Bearer " prefix
+    def extract_bearer_token
+      header = @request.env["HTTP_AUTHORIZATION"] || ""
+      header[/\ABearer (.+)\z/, 1]
+    end
+
+    # Helper method to extract Basic auth credentials from Authorization header
+    # @return [Array<String>, nil] [username, password] or nil if not Basic auth
+    def extract_basic_auth
+      header = @request.env["HTTP_AUTHORIZATION"] || ""
+      return nil unless header.start_with?("Basic ")
+
+      encoded = header[6..-1] # Remove "Basic " prefix
+      decoded = Base64.decode64(encoded)
+      decoded.split(":", 2) # Split on first colon only
+    rescue StandardError
+      nil
+    end
+
+    # Helper method to get user from common middleware env keys
+    # @return [Object, nil] User from Warden/Devise or nil
+    def user_from_middleware
+      @request.env["warden.user"] || @request.env["devise.user"]
+    end
+
+    # Helper method to get session hash
+    # @return [Hash, nil] Rack session hash or nil
+    def session
+      @request.env["rack.session"]
+    end
+
+    # Helper method to read custom env key with optional fallbacks
+    # @param keys [String, Array<String>] Primary key or array of keys to try
+    # @return [Object, nil] Value from request.env or nil
+    def env_value(*keys)
+      keys.flatten.each do |key|
+        value = @request.env[key]
+        return value if value
+      end
+      nil
+    end
+
+    # Helper method to extract API key from various common locations
+    # @param header_name [String] Custom header name (default: 'HTTP_X_API_KEY')
+    # @param param_name [String] Query/form parameter name (default: 'api_key')
+    # @return [String, nil] The API key or nil
+    def extract_api_key(header_name: "HTTP_X_API_KEY", param_name: "api_key")
+      # Try custom header first
+      api_key = @request.env[header_name]
+      return api_key if api_key
+
+      # Try Authorization header with "Bearer" prefix
+      bearer_token = extract_bearer_token
+      return bearer_token if bearer_token
+
+      # Try request parameters (query string or form data)
+      @request.params[param_name] if @request.respond_to?(:params)
+    end
+
+    # Helper method to check if user is in a development environment
+    # @return [Boolean] true if Rails.env.development?
+    def development_env?
+      Rails.env.development?
+    end
   end
 end

data/lib/action_mcp/gateway_identifiers/api_key_identifier.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module GatewayIdentifiers
+    # Example Gateway identifier for API key-based authentication.
+    #
+    # This identifier looks for API keys in various locations:
+    # - Authorization header (Bearer token)
+    # - Custom X-API-Key header
+    # - Query parameters
+    #
+    # @example Usage in ApplicationGateway
+    #   class ApplicationGateway < ActionMCP::Gateway
+    #     identified_by ActionMCP::GatewayIdentifiers::ApiKeyIdentifier
+    #   end
+    #
+    # @example Configuration
+    #   # config/mcp.yml
+    #   authentication_methods: ["api_key"]
+    #
+    # @example API Key usage
+    #   # Via Authorization header:
+    #   # Authorization: Bearer your-api-key-here
+    #   #
+    #   # Via custom header:
+    #   # X-API-Key: your-api-key-here
+    #   #
+    #   # Via query parameter:
+    #   # ?api_key=your-api-key-here
+    class ApiKeyIdentifier < ActionMCP::GatewayIdentifier
+      identifier :user
+      authenticates :api_key
+
+      def resolve
+        api_key = extract_api_key
+        raise Unauthorized, "Missing API key" unless api_key
+
+        # Look up user by API key
+        # Assumes you have an api_key or api_token field on your User model
+        user = User.find_by(api_key: api_key) || User.find_by(api_token: api_key)
+        raise Unauthorized, "Invalid API key" unless user
+
+        # Optional: Check if API key is still valid (not expired, user active, etc.)
+        if user.respond_to?(:api_key_expired?) && user.api_key_expired?
+          raise Unauthorized, "API key expired"
+        end
+
+        if user.respond_to?(:active?) && !user.active?
+          raise Unauthorized, "User account inactive"
+        end
+
+        user
+      end
+    end
+  end
+end

data/lib/action_mcp/gateway_identifiers/devise_identifier.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module GatewayIdentifiers
+    # Example Gateway identifier for direct Devise integration.
+    #
+    # This identifier looks for the user directly in request.env['devise.user'] which
+    # may be set by custom Devise middleware or helpers.
+    #
+    # @example Usage in ApplicationGateway
+    #   class ApplicationGateway < ActionMCP::Gateway
+    #     identified_by ActionMCP::GatewayIdentifiers::DeviseIdentifier
+    #   end
+    #
+    # @example Configuration
+    #   # config/mcp.yml
+    #   authentication_methods: ["devise"]
+    #
+    # @example Custom Devise middleware setup
+    #   # In your application, you might set this in a before_action:
+    #   # request.env['devise.user'] = current_user if user_signed_in?
+    class DeviseIdentifier < ActionMCP::GatewayIdentifier
+      identifier :user
+      authenticates :devise
+
+      def resolve
+        user = @request.env["devise.user"]
+        raise Unauthorized, "Not authenticated" unless user
+
+        user
+      end
+    end
+  end
+end

data/lib/action_mcp/gateway_identifiers/request_env_identifier.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module GatewayIdentifiers
+    # Example Gateway identifier for custom request environment-based authentication.
+    #
+    # This identifier looks for user information in custom request headers or environment
+    # variables. Useful for authentication set up by upstream proxies, API gateways,
+    # or custom middleware.
+    #
+    # @example Usage in ApplicationGateway
+    #   class ApplicationGateway < ActionMCP::Gateway
+    #     identified_by ActionMCP::GatewayIdentifiers::RequestEnvIdentifier
+    #   end
+    #
+    # @example Configuration
+    #   # config/mcp.yml
+    #   authentication_methods: ["request_env"]
+    #
+    # @example Nginx/Proxy setup
+    #   # Your proxy/gateway might set headers like:
+    #   # X-User-ID: 123
+    #   # X-User-Email: user@example.com
+    #   # X-User-Roles: admin,user
+    class RequestEnvIdentifier < ActionMCP::GatewayIdentifier
+      identifier :user
+      authenticates :request_env
+
+      def resolve
+        user_id = @request.env["HTTP_X_USER_ID"]
+        raise Unauthorized, "User ID header missing" unless user_id
+
+        # You might also want to get additional user info from headers
+        email = @request.env["HTTP_X_USER_EMAIL"]
+        roles = @request.env["HTTP_X_USER_ROLES"]&.split(",") || []
+
+        # Option 1: Find user in database
+        begin
+          user = User.find(user_id)
+          # Optional: verify email matches if provided
+          if email && user.email != email
+            raise Unauthorized, "User email mismatch"
+          end
+          user
+        rescue ActiveRecord::RecordNotFound
+          raise Unauthorized, "Invalid user"
+        end
+
+        # Option 2: Create a simple user object from headers (if you don't want DB lookup)
+        # OpenStruct.new(
+        #   id: user_id,
+        #   email: email,
+        #   roles: roles
+        # )
+      end
+    end
+  end
+end

data/lib/action_mcp/gateway_identifiers/warden_identifier.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module GatewayIdentifiers
+    # Example Gateway identifier for Warden-based authentication.
+    #
+    # This identifier works with Warden middleware which is commonly used by Devise.
+    # Warden sets the authenticated user in request.env['warden.user'] after successful authentication.
+    #
+    # @example Usage in ApplicationGateway
+    #   class ApplicationGateway < ActionMCP::Gateway
+    #     identified_by ActionMCP::GatewayIdentifiers::WardenIdentifier
+    #   end
+    #
+    # @example Configuration
+    #   # config/mcp.yml
+    #   authentication_methods: ["warden"]
+    #
+    # @example With Devise
+    #   # In your controller or middleware, ensure Warden is configured:
+    #   # devise_for :users
+    #   # authenticate_user! # This sets up Warden env
+    class WardenIdentifier < ActionMCP::GatewayIdentifier
+      identifier :user
+      authenticates :warden
+
+      def resolve
+        warden = @request.env["warden"]
+        raise Unauthorized, "Warden not available" unless warden
+
+        user = warden.user
+        raise Unauthorized, "Not authenticated" unless user
+
+        user
+      end
+    end
+  end
+end

data/lib/action_mcp/gateway_identifiers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  # Example Gateway identifiers for common authentication patterns.
+  #
+  # These identifiers provide ready-to-use implementations for popular
+  # Rails authentication patterns. You can use them directly or as
+  # templates for your own custom identifiers.
+  #
+  # @example Using in ApplicationGateway
+  #   class ApplicationGateway < ActionMCP::Gateway
+  #     # Use multiple identifiers (tried in order)
+  #     identified_by ActionMCP::GatewayIdentifiers::WardenIdentifier,
+  #                   ActionMCP::GatewayIdentifiers::ApiKeyIdentifier
+  #   end
+  #
+  # @example Configuration
+  #   # config/mcp.yml
+  #   authentication_methods: ["warden", "api_key"]
+  module GatewayIdentifiers
+    autoload :WardenIdentifier, "action_mcp/gateway_identifiers/warden_identifier"
+    autoload :DeviseIdentifier, "action_mcp/gateway_identifiers/devise_identifier"
+    autoload :RequestEnvIdentifier, "action_mcp/gateway_identifiers/request_env_identifier"
+    autoload :ApiKeyIdentifier, "action_mcp/gateway_identifiers/api_key_identifier"
+  end
+end

data/lib/action_mcp/json_rpc_handler_base.rb

@@ -64,8 +64,6 @@ module ActionMCP
       when %r{^notifications/}
         process_notifications(rpc_method, params)
         true
-      else
-        nil
       end
     end
 

data/lib/action_mcp/prompt.rb

@@ -28,6 +28,7 @@ module ActionMCP
     # @return [String] The default prompt name.
     def self.default_prompt_name
       return "" if name.nil?
+
       name.demodulize.underscore.sub(/_prompt$/, "")
     end
 
@@ -55,6 +56,7 @@ module ActionMCP
       def meta(data = nil)
         if data
           raise ArgumentError, "_meta must be a hash" unless data.is_a?(Hash)
+
           self._meta = _meta.merge(data)
         else
           _meta

data/lib/action_mcp/renderable.rb

@@ -49,7 +49,7 @@ module ActionMCP
     #
     def render_resource_link(uri:, name: nil, description: nil, mime_type: nil, annotations: nil)
       Content::ResourceLink.new(uri, name: name, description: description,
-                                mime_type: mime_type, annotations: annotations)
+                                     mime_type: mime_type, annotations: annotations)
     end
   end
 end

data/lib/action_mcp/resource_template.rb

@@ -27,7 +27,9 @@ module ActionMCP
       def abstract!
         @abstract = true
         # Unregister from the appropriate registry if already registered
-        ActionMCP::ResourceTemplatesRegistry.unregister(self) if ActionMCP::ResourceTemplatesRegistry.items.values.include?(self)
+        return unless ActionMCP::ResourceTemplatesRegistry.items.values.include?(self)
+
+        ActionMCP::ResourceTemplatesRegistry.unregister(self)
       end
 
       def inherited(subclass)
@@ -92,6 +94,7 @@ module ActionMCP
       def meta(data = nil)
         if data
           raise ArgumentError, "_meta must be a hash" unless data.is_a?(Hash)
+
           @_meta ||= {}
           @_meta = @_meta.merge(data)
         else
@@ -110,13 +113,14 @@ module ActionMCP
         }.compact
 
         # Add _meta if present
-        result[:_meta] = @_meta if @_meta && @_meta.any?
+        result[:_meta] = @_meta if @_meta&.any?
 
         result
       end
 
       def capability_name
         return "" if name.nil?
+
         @capability_name ||= name.demodulize.underscore.sub(/_template$/, "")
       end
 

data/lib/action_mcp/server/{memory_session.rb → base_session.rb}

@@ -2,14 +2,14 @@
 
 module ActionMCP
   module Server
-    # Memory-based session object that mimics ActiveRecord Session
-    class MemorySession
+    # Base session object that mimics ActiveRecord Session with common functionality
+    class BaseSession
       attr_accessor :id, :status, :initialized, :role, :messages_count,
                     :sse_event_counter, :protocol_version, :client_info,
                     :client_capabilities, :server_info, :server_capabilities,
                     :tool_registry, :prompt_registry, :resource_registry,
                     :created_at, :updated_at, :ended_at, :last_event_id,
-                    :session_data
+                    :session_data, :consents
 
       def initialize(attributes = {}, store = nil)
         @store = store
@@ -21,12 +21,15 @@ module ActionMCP
         @message_counter = Concurrent::AtomicFixnum.new(0)
         @new_record = true
 
+        # Initialize consents as empty hash if not provided
+        @consents = {}
+
         attributes.each do |key, value|
           send("#{key}=", value) if respond_to?("#{key}=")
         end
       end
 
-      # Mimic ActiveRecord interface
+      # ActiveRecord-like interface
       def new_record?
         @new_record
       end
@@ -37,7 +40,7 @@ module ActionMCP
 
       def save
         self.updated_at = Time.current
-        @store.save_session(self) if @store
+        @store&.save_session(self)
         @new_record = false
         true
       end
@@ -58,7 +61,7 @@ module ActionMCP
       end
 
       def destroy
-        @store.delete_session(id) if @store
+        @store&.delete_session(id)
       end
 
       def reload
@@ -133,32 +136,26 @@ module ActionMCP
         event = { event_id: event_id, data: data, created_at: Time.current }
         @sse_events << event
 
-        # Maintain cache limit
-        while @sse_events.size > max_events
-          @sse_events.shift
-        end
+        @sse_events.shift while @sse_events.size > max_events
 
         event
       end
 
       def get_sse_events_after(last_event_id, limit = 50)
-        @sse_events.select { |e| e[:event_id] > last_event_id }
-                   .first(limit)
+        @sse_events.select { |e| e[:event_id] > last_event_id }.first(limit)
       end
 
       def cleanup_old_sse_events(max_age = 15.minutes)
         cutoff_time = Time.current - max_age
+        original_size = @sse_events.size
         @sse_events.delete_if { |e| e[:created_at] < cutoff_time }
+        original_size - @sse_events.size
       end
 
-      # Calculates the maximum number of SSE events to store based on configuration
-      # @return [Integer] The maximum number of events
       def max_stored_sse_events
         ActionMCP.configuration.max_stored_sse_events || 100
       end
 
-      # Returns the SSE event retention period from configuration
-      # @return [ActiveSupport::Duration] The retention period (default: 15 minutes)
       def sse_event_retention_period
         ActionMCP.configuration.sse_event_retention_period || 15.minutes
       end
@@ -196,9 +193,9 @@ module ActionMCP
 
       # Subscription management
       def resource_subscribe(uri)
-        unless @subscriptions.any? { |s| s[:uri] == uri }
-          @subscriptions << { uri: uri, created_at: Time.current }
-        end
+        return if @subscriptions.any? { |s| s[:uri] == uri }
+
+        @subscriptions << { uri: uri, created_at: Time.current }
       end
 
       def resource_unsubscribe(uri)
@@ -310,6 +307,29 @@ module ActionMCP
         end
       end
 
+      # Consent management methods
+      def consent_granted_for?(key)
+        consents_hash = consents.is_a?(String) ? JSON.parse(consents) : consents
+        consents_hash ||= {}
+        consents_hash[key] == true
+      end
+
+      def grant_consent(key)
+        consents_hash = consents.is_a?(String) ? JSON.parse(consents) : consents
+        consents_hash ||= {}
+        consents_hash[key] = true
+        self.consents = consents_hash
+        save!
+      end
+
+      def revoke_consent(key)
+        consents_hash = consents.is_a?(String) ? JSON.parse(consents) : consents
+        consents_hash ||= {}
+        consents_hash.delete(key)
+        self.consents = consents_hash
+        save!
+      end
+
       private
 
       def normalize_name(class_or_name, type)
@@ -352,7 +372,6 @@ module ActionMCP
       end
 
       def send_tools_list_changed_notification
-        # Only send if server capabilities allow it
         return unless server_capabilities.dig("tools", "listChanged")
 
         write(JSON_RPC::Notification.new(method: "notifications/tools/list_changed"))
@@ -370,9 +389,7 @@ module ActionMCP
         write(JSON_RPC::Notification.new(method: "notifications/resources/list_changed"))
       end
 
-      public
-
-      # Simple collection classes to mimic ActiveRecord associations
+      # Collection classes
       class MessageCollection < Array
         def create!(attributes)
           self << attributes
@@ -380,7 +397,6 @@ module ActionMCP
         end
 
         def order(field)
-          # Simple ordering implementation
           sort_by { |msg| msg[field] || msg[field.to_s] }
         end
       end
@@ -413,8 +429,7 @@ module ActionMCP
           size
         end
 
-        def where(condition, value)
-          # Simple implementation for "event_id > ?" condition
+        def where(_condition, value)
           select { |e| e[:event_id] > value }
         end