actionmcp 0.52.2 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a11c68a5511cb3cafd2f90ae24aa31e2099f41c8b4ee3d357719574f598752d4
-  data.tar.gz: 145398e069f03f6bd2697a16efca476d47983ccdcf84f3730f9ea0b0223eec03
+  metadata.gz: 961fd09ccf447057085e6e63d38c64079b460917d48d70c5ad5dc53ee0c3154f
+  data.tar.gz: c74e249d91903199a65afa5ecad8ff55bf188aa7e48167742c26aa20396913cf
 SHA512:
-  metadata.gz: 9bb02d28a5b99c70bde877ab7e481619c26d55f68b47fbebc40e384400fc445c4683e04e35ac6bc9f837028bb5af9ec84928662fb8fd93e80e3a7bcec446e6ad
-  data.tar.gz: 78c11ff2bc200f7a482ffefc516b2ab2ad487399b37685d3fe49cd907de6b1e6a3aafd891ea584b3b2387c4567c4d58c1ed9db5d6aaca35b065ac613f505c4d8
+  metadata.gz: 0f3637e231ef5d5f668d548c41a3d71c121946b4002d56faf27b6fe1941e8f5fb2cf3ed70b0bb49a370055124777ef7300bf3bec174cfa2802c321bbd56f95b2
+  data.tar.gz: d1066a9642357aa64e77e0bcbdfb99205dbbbe27140262d41aa0bc61aad900e007d6da5a0a136ed116e101fba365066184bb16602cff3caed3c755ddfca8d9bc

data/README.md

@@ -493,6 +493,8 @@ This will create `config/mcp.yml` with example configurations for all environmen
 
 ActionMCP provides a Gateway system similar to ActionCable's Connection for handling authentication. The Gateway allows you to authenticate users and make them available throughout your MCP components.
 
+ActionMCP supports multiple authentication methods including OAuth 2.1, JWT tokens, and no authentication for development. For detailed OAuth 2.1 configuration and usage, see the [OAuth Authentication Guide](OAUTH.md).
+
 ### Creating an ApplicationGateway
 
 When you run the install generator, it creates an `ApplicationGateway` class:

data/app/controllers/action_mcp/oauth/endpoints_controller.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module ActionMCP
+  module OAuth
+    # OAuth 2.1 endpoints controller
+    # Handles authorization, token, introspection, and revocation endpoints
+    class EndpointsController < ActionController::Base
+      protect_from_forgery with: :null_session
+      before_action :check_oauth_enabled
+
+      # GET /oauth/authorize
+      # Authorization endpoint for OAuth 2.1 authorization code flow
+      def authorize
+        # Extract parameters
+        client_id = params[:client_id]
+        redirect_uri = params[:redirect_uri]
+        response_type = params[:response_type]
+        scope = params[:scope]
+        state = params[:state]
+        code_challenge = params[:code_challenge]
+        code_challenge_method = params[:code_challenge_method]
+
+        # Validate required parameters
+        if client_id.blank? || redirect_uri.blank? || response_type.blank?
+          return render_error("invalid_request", "Missing required parameters")
+        end
+
+        # Validate response type
+        unless response_type == "code"
+          return render_error("unsupported_response_type", "Only authorization code flow supported")
+        end
+
+        # Validate PKCE if required
+        if oauth_config["pkce_required"] && code_challenge.blank?
+          return render_error("invalid_request", "PKCE required")
+        end
+
+        # In a real implementation, this would show a consent page
+        # For now, we'll auto-approve for configured clients
+        if auto_approve_client?(client_id)
+          # Generate authorization code
+          user_id = current_user&.id || "anonymous"
+
+          begin
+            code = ActionMCP::OAuth::Provider.generate_authorization_code(
+              client_id: client_id,
+              redirect_uri: redirect_uri,
+              scope: scope || default_scope,
+              code_challenge: code_challenge,
+              code_challenge_method: code_challenge_method,
+              user_id: user_id
+            )
+
+            # Redirect back to client with authorization code
+            redirect_params = { code: code }
+            redirect_params[:state] = state if state
+            redirect_to "#{redirect_uri}?#{redirect_params.to_query}", allow_other_host: true
+          rescue ActionMCP::OAuth::Error => e
+            render_error(e.oauth_error_code, e.message)
+          end
+        else
+          # In production, show consent page
+          render_consent_page(client_id, redirect_uri, scope, state, code_challenge, code_challenge_method)
+        end
+      end
+
+      # POST /oauth/token
+      # Token endpoint for exchanging authorization codes and refreshing tokens
+      def token
+        grant_type = params[:grant_type]
+
+        case grant_type
+        when "authorization_code"
+          handle_authorization_code_grant
+        when "refresh_token"
+          handle_refresh_token_grant
+        when "client_credentials"
+          handle_client_credentials_grant
+        else
+          render_token_error("unsupported_grant_type", "Unsupported grant type")
+        end
+      rescue ActionMCP::OAuth::Error => e
+        render_token_error(e.oauth_error_code, e.message)
+      end
+
+      # POST /oauth/introspect
+      # Token introspection endpoint (RFC 7662)
+      def introspect
+        token = params[:token]
+        return render_introspection_error unless token
+
+        # Authenticate client for introspection
+        client_id, client_secret = extract_client_credentials
+        return render_introspection_error unless client_id
+
+        begin
+          token_info = ActionMCP::OAuth::Provider.introspect_token(token)
+          render json: token_info
+        rescue ActionMCP::OAuth::Error
+          render json: { active: false }
+        end
+      end
+
+      # POST /oauth/revoke
+      # Token revocation endpoint (RFC 7009)
+      def revoke
+        token = params[:token]
+        token_type_hint = params[:token_type_hint]
+
+        return head :bad_request unless token
+
+        # Authenticate client
+        client_id, client_secret = extract_client_credentials
+        return head :unauthorized unless client_id
+
+        begin
+          ActionMCP::OAuth::Provider.revoke_token(token, token_type_hint: token_type_hint)
+          head :ok
+        rescue ActionMCP::OAuth::Error
+          head :bad_request
+        end
+      end
+
+      private
+
+      def check_oauth_enabled
+        auth_methods = ActionMCP.configuration.authentication_methods
+        unless auth_methods&.include?("oauth")
+          head :not_found
+        end
+      end
+
+      def oauth_config
+        @oauth_config ||= ActionMCP.configuration.oauth_config || {}
+      end
+
+      def handle_authorization_code_grant
+        code = params[:code]
+        client_id = params[:client_id]
+        client_secret = params[:client_secret]
+        redirect_uri = params[:redirect_uri]
+        code_verifier = params[:code_verifier]
+
+        # Extract client credentials from Authorization header if not in params
+        if client_id.blank?
+          client_id, client_secret = extract_client_credentials
+        end
+
+        return render_token_error("invalid_request", "Missing required parameters") if code.blank? || client_id.blank?
+
+        token_response = ActionMCP::OAuth::Provider.exchange_code_for_token(
+          code: code,
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          code_verifier: code_verifier
+        )
+
+        render json: token_response
+      end
+
+      def handle_refresh_token_grant
+        refresh_token = params[:refresh_token]
+        scope = params[:scope]
+
+        # Extract client credentials
+        client_id, client_secret = extract_client_credentials
+        client_id ||= params[:client_id]
+        client_secret ||= params[:client_secret]
+
+        return render_token_error("invalid_request", "Missing required parameters") if refresh_token.blank? || client_id.blank?
+
+        token_response = ActionMCP::OAuth::Provider.refresh_access_token(
+          refresh_token: refresh_token,
+          client_id: client_id,
+          client_secret: client_secret,
+          scope: scope
+        )
+
+        render json: token_response
+      end
+
+      def handle_client_credentials_grant
+        scope = params[:scope]
+
+        # Extract client credentials
+        client_id, client_secret = extract_client_credentials
+        client_id ||= params[:client_id]
+        client_secret ||= params[:client_secret]
+
+        return render_token_error("invalid_request", "Missing client credentials") if client_id.blank?
+
+        token_response = ActionMCP::OAuth::Provider.client_credentials_grant(
+          client_id: client_id,
+          client_secret: client_secret,
+          scope: scope
+        )
+
+        render json: token_response
+      end
+
+      def extract_client_credentials
+        auth_header = request.headers["Authorization"]
+        if auth_header&.start_with?("Basic ")
+          encoded = auth_header.split(" ", 2).last
+          decoded = Base64.decode64(encoded)
+          decoded.split(":", 2)
+        else
+          [ nil, nil ]
+        end
+      end
+
+      def auto_approve_client?(client_id)
+        # In development/testing, auto-approve known clients
+        # In production, this should check a proper client registry
+        Rails.env.development? || Rails.env.test? || oauth_config["auto_approve_clients"]&.include?(client_id)
+      end
+
+      def current_user
+        # This should be implemented by the application
+        # For now, return a default user for development
+        if Rails.env.development? || Rails.env.test?
+          OpenStruct.new(id: "dev_user", email: "dev@example.com")
+        else
+          # In production, this should integrate with your authentication system
+          nil
+        end
+      end
+
+      def default_scope
+        oauth_config["default_scope"] || "mcp:tools mcp:resources mcp:prompts"
+      end
+
+      def render_error(error_code, description)
+        render json: {
+          error: error_code,
+          error_description: description
+        }, status: :bad_request
+      end
+
+      def render_token_error(error_code, description)
+        render json: {
+          error: error_code,
+          error_description: description
+        }, status: :bad_request
+      end
+
+      def render_introspection_error
+        render json: { active: false }, status: :bad_request
+      end
+
+      def render_consent_page(client_id, redirect_uri, scope, state, code_challenge, code_challenge_method)
+        # In production, this would render a proper consent page
+        # For now, just auto-deny unknown clients
+        render json: {
+          error: "access_denied",
+          error_description: "User denied authorization"
+        }, status: :forbidden
+      end
+    end
+  end
+end

data/app/controllers/action_mcp/oauth/metadata_controller.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module OAuth
+    # Controller for OAuth 2.1 metadata endpoints
+    # Provides server discovery information as per RFC 8414
+    class MetadataController < ActionController::Base
+      before_action :check_oauth_enabled
+
+      # GET /.well-known/oauth-authorization-server
+      # Returns OAuth Authorization Server Metadata as per RFC 8414
+      def authorization_server
+        metadata = {
+          issuer: issuer_url,
+          authorization_endpoint: authorization_endpoint,
+          token_endpoint: token_endpoint,
+          introspection_endpoint: introspection_endpoint,
+          revocation_endpoint: revocation_endpoint,
+          response_types_supported: response_types_supported,
+          grant_types_supported: grant_types_supported,
+          token_endpoint_auth_methods_supported: token_endpoint_auth_methods_supported,
+          scopes_supported: scopes_supported,
+          code_challenge_methods_supported: code_challenge_methods_supported,
+          service_documentation: service_documentation
+        }
+
+        # Add optional fields based on configuration
+        if oauth_config["enable_dynamic_registration"]
+          metadata[:registration_endpoint] = registration_endpoint
+        end
+
+        if oauth_config["jwks_uri"]
+          metadata[:jwks_uri] = oauth_config["jwks_uri"]
+        end
+
+        render json: metadata
+      end
+
+      # GET /.well-known/oauth-protected-resource
+      # Returns Protected Resource Metadata as per RFC 8705
+      def protected_resource
+        metadata = {
+          resource: issuer_url,
+          authorization_servers: [ issuer_url ],
+          scopes_supported: scopes_supported,
+          bearer_methods_supported: [ "header" ],
+          resource_documentation: resource_documentation
+        }
+
+        render json: metadata
+      end
+
+      private
+
+      def check_oauth_enabled
+        auth_methods = ActionMCP.configuration.authentication_methods
+        unless auth_methods&.include?("oauth")
+          head :not_found
+        end
+      end
+
+      def oauth_config
+        @oauth_config ||= ActionMCP.configuration.oauth_config || {}
+      end
+
+      def issuer_url
+        @issuer_url ||= oauth_config["issuer_url"] || request.base_url
+      end
+
+      def authorization_endpoint
+        "#{issuer_url}/oauth/authorize"
+      end
+
+      def token_endpoint
+        "#{issuer_url}/oauth/token"
+      end
+
+      def introspection_endpoint
+        "#{issuer_url}/oauth/introspect"
+      end
+
+      def revocation_endpoint
+        "#{issuer_url}/oauth/revoke"
+      end
+
+      def registration_endpoint
+        "#{issuer_url}/oauth/register"
+      end
+
+      def response_types_supported
+        [ "code" ]
+      end
+
+      def grant_types_supported
+        grants = [ "authorization_code" ]
+        grants << "refresh_token" if oauth_config["enable_refresh_tokens"]
+        grants << "client_credentials" if oauth_config["enable_client_credentials"]
+        grants
+      end
+
+      def token_endpoint_auth_methods_supported
+        methods = [ "client_secret_basic", "client_secret_post" ]
+        methods << "none" if oauth_config["allow_public_clients"]
+        methods
+      end
+
+      def scopes_supported
+        oauth_config["scopes_supported"] || [ "mcp:tools", "mcp:resources", "mcp:prompts" ]
+      end
+
+      def code_challenge_methods_supported
+        methods = []
+        if oauth_config["pkce_required"] || oauth_config["pkce_supported"]
+          methods << "S256"
+          methods << "plain" if oauth_config["allow_plain_pkce"]
+        end
+        methods
+      end
+
+      def service_documentation
+        oauth_config["service_documentation"] || "#{request.base_url}/docs"
+      end
+
+      def resource_documentation
+        oauth_config["resource_documentation"] || "#{request.base_url}/docs/api"
+      end
+    end
+  end
+end

data/app/models/action_mcp/session.rb

@@ -5,11 +5,16 @@
 # Table name: action_mcp_sessions
 #
 #  id                                                  :string           not null, primary key
+#  authentication_method                               :string           default("none")
 #  client_capabilities(The capabilities of the client) :jsonb
 #  client_info(The information about the client)       :jsonb
 #  ended_at(The time the session ended)                :datetime
 #  initialized                                         :boolean          default(FALSE), not null
 #  messages_count                                      :integer          default(0), not null
+#  oauth_access_token                                  :string
+#  oauth_refresh_token                                 :string
+#  oauth_token_expires_at                              :datetime
+#  oauth_user_context                                  :jsonb
 #  prompt_registry                                     :jsonb
 #  protocol_version                                    :string
 #  resource_registry                                   :jsonb
@@ -22,6 +27,12 @@
 #  created_at                                          :datetime         not null
 #  updated_at                                          :datetime         not null
 #
+# Indexes
+#
+#  index_action_mcp_sessions_on_authentication_method   (authentication_method)
+#  index_action_mcp_sessions_on_oauth_access_token      (oauth_access_token) UNIQUE
+#  index_action_mcp_sessions_on_oauth_token_expires_at  (oauth_token_expires_at)
+#
 module ActionMCP
   ##
   # Represents an MCP session, which is a connection between a client and a server.
@@ -323,6 +334,94 @@ module ActionMCP
       end
     end
 
+    # OAuth Session Management
+    # Required by MCP 2025-03-26 specification for session binding
+
+    # Store OAuth token and user context in session
+    def store_oauth_token(access_token:, refresh_token: nil, expires_at:, user_context: {})
+      update!(
+        oauth_access_token: access_token,
+        oauth_refresh_token: refresh_token,
+        oauth_token_expires_at: expires_at,
+        oauth_user_context: user_context,
+        authentication_method: "oauth"
+      )
+    end
+
+    # Retrieve OAuth token information
+    def oauth_token_info
+      return nil unless oauth_access_token
+
+      {
+        access_token: oauth_access_token,
+        refresh_token: oauth_refresh_token,
+        expires_at: oauth_token_expires_at,
+        user_context: oauth_user_context || {},
+        authentication_method: authentication_method
+      }
+    end
+
+    # Check if OAuth token is valid and not expired
+    def oauth_token_valid?
+      return false unless oauth_access_token
+      return true unless oauth_token_expires_at
+
+      oauth_token_expires_at > Time.current
+    end
+
+    # Clear OAuth token data
+    def clear_oauth_token!
+      update!(
+        oauth_access_token: nil,
+        oauth_refresh_token: nil,
+        oauth_token_expires_at: nil,
+        oauth_user_context: nil,
+        authentication_method: "none"
+      )
+    end
+
+    # Update OAuth token (for refresh flow)
+    def update_oauth_token(access_token:, refresh_token: nil, expires_at:)
+      update!(
+        oauth_access_token: access_token,
+        oauth_refresh_token: refresh_token,
+        oauth_token_expires_at: expires_at
+      )
+    end
+
+    # Get user information from OAuth context
+    def oauth_user
+      return nil unless oauth_user_context.is_a?(Hash)
+
+      OpenStruct.new(oauth_user_context)
+    end
+
+    # Check if session is authenticated via OAuth
+    def oauth_authenticated?
+      authentication_method == "oauth" && oauth_token_valid?
+    end
+
+    # Find session by OAuth access token (class method)
+    def self.find_by_oauth_token(access_token)
+      find_by(oauth_access_token: access_token)
+    end
+
+    # Find sessions with expired OAuth tokens (class method)
+    def self.with_expired_oauth_tokens
+      where("oauth_token_expires_at IS NOT NULL AND oauth_token_expires_at < ?", Time.current)
+    end
+
+    # Cleanup expired OAuth tokens (class method)
+    def self.cleanup_expired_oauth_tokens
+      with_expired_oauth_tokens.update_all(
+        oauth_access_token: nil,
+        oauth_refresh_token: nil,
+        oauth_token_expires_at: nil,
+        oauth_user_context: nil,
+        authentication_method: "none"
+      )
+    end
+
     private
 
     # if this session is from a server, the writer is the client

data/config/routes.rb

@@ -3,6 +3,16 @@
 ActionMCP::Engine.routes.draw do
   get "/up", to: "/rails/health#show", as: :action_mcp_health_check
 
+  # OAuth 2.1 metadata endpoints
+  get "/.well-known/oauth-authorization-server", to: "oauth/metadata#authorization_server", as: :oauth_authorization_server_metadata
+  get "/.well-known/oauth-protected-resource", to: "oauth/metadata#protected_resource", as: :oauth_protected_resource_metadata
+
+  # OAuth 2.1 endpoints
+  get "/oauth/authorize", to: "oauth/endpoints#authorize", as: :oauth_authorize
+  post "/oauth/token", to: "oauth/endpoints#token", as: :oauth_token
+  post "/oauth/introspect", to: "oauth/endpoints#introspect", as: :oauth_introspect
+  post "/oauth/revoke", to: "oauth/endpoints#revoke", as: :oauth_revoke
+
   # MCP 2025-03-26 Spec routes
   get "/", to: "application#show", as: :mcp_get
   post "/", to: "application#create", as: :mcp_post

data/db/migrate/20250608112101_add_oauth_to_sessions.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class AddOAuthToSessions < ActiveRecord::Migration[8.0]
+  def change
+    # Use jsonb for PostgreSQL, json for other databases (SQLite3, MySQL)
+    json_type = connection.adapter_name.downcase == 'postgresql' ? :jsonb : :json
+
+    add_column :action_mcp_sessions, :oauth_access_token, :string
+    add_column :action_mcp_sessions, :oauth_refresh_token, :string
+    add_column :action_mcp_sessions, :oauth_token_expires_at, :datetime
+    add_column :action_mcp_sessions, :oauth_user_context, json_type
+    add_column :action_mcp_sessions, :authentication_method, :string, default: "none"
+
+    # Add indexes for performance
+    add_index :action_mcp_sessions, :oauth_access_token, unique: true
+    add_index :action_mcp_sessions, :oauth_token_expires_at
+    add_index :action_mcp_sessions, :authentication_method
+  end
+end

data/lib/action_mcp/client/oauth_client_provider/memory_storage.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Client
+    class OauthClientProvider
+      # Simple in-memory storage for development
+      # In production, use persistent storage
+      class MemoryStorage
+        def initialize
+          @data = {}
+        end
+
+        def save_tokens(tokens)
+          @data[:tokens] = tokens
+        end
+
+        def load_tokens
+          @data[:tokens]
+        end
+
+        def clear_tokens
+          @data.delete(:tokens)
+        end
+
+        def save_code_verifier(verifier)
+          @data[:code_verifier] = verifier
+        end
+
+        def load_code_verifier
+          @data[:code_verifier]
+        end
+
+        def clear_code_verifier
+          @data.delete(:code_verifier)
+        end
+
+        def save_client_information(info)
+          @data[:client_information] = info
+        end
+
+        def load_client_information
+          @data[:client_information]
+        end
+      end
+    end
+  end
+end