mathpix 0.1.0

data/lib/mathpix/mcp/auth/oauth_provider.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'json'
+require 'base64'
+require 'openssl'
+require 'digest'
+
+module Mathpix
+  module MCP
+    module Auth
+      # OAuth 2.0 Provider implementation
+      class OAuthProvider
+        AUTHORIZATION_CODE_EXPIRY = 600 # 10 minutes
+        ACCESS_TOKEN_EXPIRY = 3600 # 1 hour
+        REFRESH_TOKEN_EXPIRY = 2_592_000 # 30 days
+
+        def initialize
+          @clients = {}
+          @authorization_codes = {}
+          @access_tokens = {}
+          @refresh_tokens = {}
+          @revoked_tokens = {}
+          @jwt_secret = ENV['JWT_SECRET'] || SecureRandom.hex(32)
+        end
+
+        def register_client(client_id:, client_secret:, redirect_uri:, name: nil)
+          raise ArgumentError, 'client_id required' if client_id.nil?
+          raise ArgumentError, 'redirect_uri required' if redirect_uri.nil?
+
+          @clients[client_id] = {
+            client_secret: client_secret,
+            redirect_uri: redirect_uri,
+            name: name
+          }
+        end
+
+        def client_exists?(client_id)
+          @clients.key?(client_id)
+        end
+
+        def get_authorization(code)
+          @authorization_codes[code]
+        end
+
+        # Authorization code grant flow
+        def authorize(client_id:, redirect_uri:, scope:, user_id:, state: nil, code_challenge: nil, code_challenge_method: nil)
+          raise InvalidClientError, 'Unknown client' unless @clients.key?(client_id)
+
+          client = @clients[client_id]
+          raise InvalidRedirectUriError, 'Mismatched redirect_uri' unless client[:redirect_uri] == redirect_uri
+
+          code = SecureRandom.hex(32)
+
+          @authorization_codes[code] = {
+            client_id: client_id,
+            redirect_uri: redirect_uri,
+            scope: scope,
+            user_id: user_id,
+            state: state,
+            code_challenge: code_challenge,
+            code_challenge_method: code_challenge_method,
+            expires_at: Time.now + AUTHORIZATION_CODE_EXPIRY,
+            used: false
+          }
+
+          code
+        end
+
+        def exchange_code(code:, client_id:, client_secret:, redirect_uri:, code_verifier: nil)
+          auth = @authorization_codes[code]
+
+          raise InvalidGrantError, 'Invalid authorization code' if auth.nil?
+          raise InvalidGrantError, 'Authorization code already used' if auth[:used]
+          raise InvalidGrantError, 'Authorization code expired' if Time.now > auth[:expires_at]
+          raise InvalidClientError, 'Invalid client' unless validate_client(client_id, client_secret)
+          raise InvalidGrantError, 'Mismatched redirect_uri' unless auth[:redirect_uri] == redirect_uri
+
+          # PKCE verification
+          if auth[:code_challenge]
+            raise InvalidGrantError, 'Code verifier required' if code_verifier.nil?
+            unless verify_pkce(code_verifier, auth[:code_challenge], auth[:code_challenge_method])
+              raise InvalidGrantError, 'Invalid code verifier'
+            end
+          end
+
+          # Mark code as used
+          auth[:used] = true
+
+          # Generate tokens
+          access_token = generate_access_token(
+            user_id: auth[:user_id],
+            client_id: client_id,
+            scope: auth[:scope]
+          )
+
+          refresh_token = generate_refresh_token(
+            user_id: auth[:user_id],
+            client_id: client_id,
+            scope: auth[:scope]
+          )
+
+          {
+            access_token: access_token,
+            token_type: 'Bearer',
+            expires_in: ACCESS_TOKEN_EXPIRY,
+            refresh_token: refresh_token,
+            scope: auth[:scope]
+          }
+        end
+
+        def refresh_token(refresh_token:, client_id:, client_secret:)
+          raise InvalidClientError, 'Invalid client' unless validate_client(client_id, client_secret)
+
+          token_data = @refresh_tokens[refresh_token]
+          raise InvalidGrantError, 'Invalid refresh token' if token_data.nil?
+          raise InvalidGrantError, 'Refresh token expired' if Time.now > token_data[:expires_at]
+          raise InvalidGrantError, 'Refresh token revoked' if @revoked_tokens.key?(refresh_token)
+
+          # Invalidate old refresh token (rotation)
+          @refresh_tokens.delete(refresh_token)
+          @revoked_tokens[refresh_token] = Time.now
+
+          # Generate new tokens
+          access_token = generate_access_token(
+            user_id: token_data[:user_id],
+            client_id: client_id,
+            scope: token_data[:scope]
+          )
+
+          new_refresh_token = generate_refresh_token(
+            user_id: token_data[:user_id],
+            client_id: client_id,
+            scope: token_data[:scope]
+          )
+
+          {
+            access_token: access_token,
+            token_type: 'Bearer',
+            expires_in: ACCESS_TOKEN_EXPIRY,
+            refresh_token: new_refresh_token,
+            scope: token_data[:scope]
+          }
+        end
+
+        def validate_token(token)
+          raise InvalidTokenError, 'Token revoked' if @revoked_tokens.key?(token)
+
+          payload = decode_jwt(token)
+          raise InvalidTokenError, 'Token expired' if Time.now.to_i > payload['exp']
+
+          payload
+        rescue OpenSSL::OpenSSLError, StandardError => e
+          raise InvalidTokenError, "Invalid token signature: #{e.message}"
+        end
+
+        def validate_scope(token_scope, required_scope)
+          token_scopes = token_scope.split
+          required_scopes = required_scope.split
+
+          # Admin scope grants all
+          return true if token_scopes.include?('admin')
+
+          # Check if all required scopes are present
+          required_scopes.all? { |scope| token_scopes.include?(scope) }
+        end
+
+        def introspect_token(token, client_id: nil, client_secret: nil)
+          # Validate client if credentials provided
+          if client_id && client_secret
+            raise InvalidClientError, 'Invalid client' unless validate_client(client_id, client_secret)
+          end
+
+          begin
+            payload = validate_token(token)
+
+            {
+              active: true,
+              scope: payload['scope'],
+              client_id: payload['client_id'],
+              exp: payload['exp']
+            }
+          rescue InvalidTokenError
+            { active: false }
+          end
+        end
+
+        def revoke_token(token, client_id: nil, client_secret: nil)
+          # Validate client if credentials provided
+          if client_id && client_secret
+            raise InvalidClientError, 'Invalid client' unless validate_client(client_id, client_secret)
+          end
+
+          @revoked_tokens[token] = Time.now
+
+          # If it's a refresh token, also revoke associated access tokens
+          if @refresh_tokens[token]
+            token_data = @refresh_tokens[token]
+            @refresh_tokens.delete(token)
+
+            # Revoke all access tokens for this user/client combination
+            @access_tokens.select do |access_token, data|
+              data[:user_id] == token_data[:user_id] && data[:client_id] == token_data[:client_id]
+            end.each_key do |access_token|
+              @revoked_tokens[access_token] = Time.now
+            end
+          end
+
+          true
+        end
+
+        def client_credentials(client_id:, client_secret:, scope:)
+          raise InvalidClientError, 'Invalid client' unless validate_client(client_id, client_secret)
+
+          access_token = generate_access_token(
+            user_id: nil, # No user for client credentials
+            client_id: client_id,
+            scope: scope
+          )
+
+          {
+            access_token: access_token,
+            token_type: 'Bearer',
+            expires_in: ACCESS_TOKEN_EXPIRY
+            # No refresh token for client credentials flow
+          }
+        end
+        alias client_credentials_grant client_credentials
+
+        # Public test helpers (used by step definitions)
+        def store_authorization_code(code:, client_id:, redirect_uri:, scope:)
+          @authorization_codes[code] = {
+            client_id: client_id,
+            redirect_uri: redirect_uri,
+            scope: scope,
+            user_id: 'test_user',
+            expires_at: Time.now + AUTHORIZATION_CODE_EXPIRY,
+            used: false
+          }
+        end
+
+        def decode_token(token)
+          decode_jwt(token)
+        end
+
+        private
+
+        def validate_client(client_id, client_secret)
+          client = @clients[client_id]
+          return false if client.nil?
+
+          client[:client_secret] == client_secret
+        end
+
+        def generate_access_token(user_id:, client_id:, scope:)
+          now = Time.now.to_i
+
+          payload = {
+            user_id: user_id,
+            client_id: client_id,
+            scope: scope,
+            iat: now,
+            exp: now + ACCESS_TOKEN_EXPIRY,
+            aud: 'mathpix-mcp-server',
+            iss: 'mathpix-oauth'
+          }
+
+          token = encode_jwt(payload)
+
+          @access_tokens[token] = {
+            user_id: user_id,
+            client_id: client_id,
+            scope: scope,
+            expires_at: Time.at(now + ACCESS_TOKEN_EXPIRY)
+          }
+
+          token
+        end
+
+        def generate_refresh_token(user_id:, client_id:, scope:)
+          token = SecureRandom.hex(32)
+
+          @refresh_tokens[token] = {
+            user_id: user_id,
+            client_id: client_id,
+            scope: scope,
+            expires_at: Time.now + REFRESH_TOKEN_EXPIRY
+          }
+
+          token
+        end
+
+        def encode_jwt(payload)
+          header = {
+            alg: 'HS256',
+            typ: 'JWT'
+          }
+
+          header_encoded = base64url_encode(JSON.generate(header))
+          payload_encoded = base64url_encode(JSON.generate(payload))
+
+          signature_input = "#{header_encoded}.#{payload_encoded}"
+          signature = OpenSSL::HMAC.digest('SHA256', @jwt_secret, signature_input)
+          signature_encoded = base64url_encode(signature)
+
+          "#{header_encoded}.#{payload_encoded}.#{signature_encoded}"
+        end
+
+        def decode_jwt(token)
+          header_encoded, payload_encoded, signature_encoded = token.split('.')
+
+          # Verify signature
+          signature_input = "#{header_encoded}.#{payload_encoded}"
+          expected_signature = OpenSSL::HMAC.digest('SHA256', @jwt_secret, signature_input)
+          expected_signature_encoded = base64url_encode(expected_signature)
+
+          unless signature_encoded == expected_signature_encoded
+            raise InvalidTokenError, 'Invalid signature'
+          end
+
+          JSON.parse(base64url_decode(payload_encoded))
+        end
+
+        def verify_pkce(code_verifier, code_challenge, method)
+          case method
+          when 'S256'
+            computed = Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
+            computed == code_challenge
+          when 'plain'
+            code_verifier == code_challenge
+          else
+            false
+          end
+        end
+
+        def base64url_encode(data)
+          Base64.urlsafe_encode64(data, padding: false)
+        end
+
+        def base64url_decode(data)
+          Base64.urlsafe_decode64(data)
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/auth/token_manager.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Auth
+      # Token storage and management
+      class TokenManager
+        def initialize
+          @tokens = {}
+        end
+
+        def store_token(token, data)
+          @tokens[token] = data
+        end
+
+        def get_token(token)
+          @tokens[token]
+        end
+
+        def revoke_token(token)
+          @tokens.delete(token)
+        end
+
+        def cleanup_expired
+          now = Time.now
+          @tokens.reject! { |_, data| data[:expires_at] && data[:expires_at] < now }
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/auth.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Auth
+      # Custom error classes
+      class AuthError < StandardError; end
+      class InvalidClientError < AuthError; end
+      class InvalidGrantError < AuthError; end
+      class InvalidTokenError < AuthError; end
+      class InvalidRedirectUriError < AuthError; end
+      class InsufficientScopeError < AuthError; end
+    end
+  end
+end
+
+require_relative 'auth/oauth_provider'
+require_relative 'auth/token_manager'

data/lib/mathpix/mcp/base_tool.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Tools
+      # Base class for all Mathpix MCP tools
+      #
+      # Uses official Ruby MCP SDK (MCP::Tool)
+      # Provides common utilities for Mathpix-specific tools
+      #
+      # The geodesic path: official SDK base + Mathpix utilities
+      #
+      # @example Tool implementation
+      #   class ExampleTool < BaseTool
+      #     description "Example tool"
+      #     input_schema(
+      #       properties: { message: { type: "string" } },
+      #       required: ["message"]
+      #     )
+      #
+      #     def self.call(message:, server_context:)
+      #       client = server_context[:mathpix_client]
+      #       # Use client to make API calls
+      #       text_response("Result: #{message}")
+      #     end
+      #   end
+      class BaseTool < ::MCP::Tool
+        class << self
+          protected
+
+          # Get Mathpix client from server context
+          #
+          # @param server_context [Hash] MCP server context
+          # @return [Mathpix::Client] Mathpix API client
+          def mathpix_client(server_context)
+            server_context[:mathpix_client] || raise(ArgumentError, "mathpix_client not in server_context")
+          end
+
+          # Create text response (official MCP format)
+          #
+          # @param text [String] response text
+          # @return [::MCP::Tool::Response]
+          def text_response(text)
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: text
+            }])
+          end
+
+          # Create JSON response with text wrapper
+          #
+          # @param data [Hash] JSON data
+          # @return [::MCP::Tool::Response]
+          def json_response(data)
+            text_response(JSON.pretty_generate(data))
+          end
+
+          # Create error response
+          #
+          # @param error [StandardError, String] error object or message
+          # @return [::MCP::Tool::Response]
+          def error_response(error)
+            message = error.is_a?(StandardError) ? error.message : error.to_s
+            details = error.is_a?(Mathpix::Error) ? error.details : {}
+
+            error_data = {
+              error: true,
+              message: message,
+              type: error.class.name
+            }
+            error_data[:details] = details unless details.empty?
+
+            json_response(error_data)
+          end
+
+          # Extract formats from arguments
+          #
+          # @param formats [Array, nil] format array
+          # @param client [Mathpix::Client] client for defaults
+          # @return [Array<Symbol>] format symbols
+          def extract_formats(formats, client)
+            return client.config.default_formats if formats.nil? || formats.empty?
+            Array(formats).map(&:to_sym)
+          end
+
+          # Normalize path (expand ~, resolve relative paths)
+          #
+          # @param path [String] file path
+          # @return [String] normalized path
+          def normalize_path(path)
+            File.expand_path(path) rescue path
+          end
+
+          # Check if path is a URL
+          #
+          # @param path [String] path or URL
+          # @return [Boolean]
+          def url?(path)
+            path.to_s.start_with?('http://', 'https://')
+          end
+
+          # Safe execute with error handling
+          #
+          # @yield Block to execute
+          # @return [::MCP::Tool::Response]
+          def safe_execute
+            yield
+          rescue Mathpix::Error => e
+            error_response(e)
+          rescue StandardError => e
+            error_response(e)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mathpix/mcp/elicitations/ambiguity_elicitation.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Mathpix
+  module MCP
+    module Elicitations
+      # Ambiguity elicitation for mathematical notation disambiguation
+      #
+      # When OCR detects ambiguous symbols, prompts user to clarify
+      # E.g., "0" vs "O", "1" vs "l", partial fractions, etc.
+      #
+      # @example Ambiguous symbol
+      #   elicitation = AmbiguityElicitation.new(
+      #     ambiguous_text: "O",
+      #     context: "x + O = 5",
+      #     alternatives: ["0 (zero)", "O (letter O)"]
+      #   )
+      #   response = elicitation.request_clarification
+      #
+      class AmbiguityElicitation
+        # Common ambiguous patterns in mathematical notation
+        AMBIGUOUS_PATTERNS = {
+          'O_or_0' => {
+            pattern: /[O0]/,
+            alternatives: ['0 (zero)', 'O (letter O)'],
+            description: 'Zero vs letter O ambiguity'
+          },
+          '1_or_l' => {
+            pattern: /[1lI]/,
+            alternatives: ['1 (one)', 'l (lowercase L)', 'I (uppercase i)'],
+            description: 'One vs lowercase L vs uppercase I'
+          },
+          'comma_or_decimal' => {
+            pattern: /\d[.,]\d/,
+            alternatives: ['comma (thousands separator)', 'decimal point'],
+            description: 'Comma vs decimal point in numbers'
+          },
+          'prime_or_apostrophe' => {
+            pattern: /[\'′]/,
+            alternatives: ["' (prime)", "' (apostrophe)"],
+            description: 'Prime notation vs apostrophe'
+          }
+        }.freeze
+
+        attr_reader :ambiguous_text, :context, :alternatives, :decision
+
+        # Initialize ambiguity elicitation
+        #
+        # @param ambiguous_text [String] the ambiguous symbol/text
+        # @param context [String] surrounding LaTeX for context
+        # @param alternatives [Array<String>] possible interpretations
+        # @param position [Hash] optional position data {x, y, width, height}
+        def initialize(ambiguous_text:, context:, alternatives: nil, position: nil)
+          @ambiguous_text = ambiguous_text
+          @context = context
+          @position = position
+          @alternatives = alternatives || detect_alternatives
+          @decision = nil
+        end
+
+        # Generate disambiguation prompt
+        #
+        # @return [String] user-facing prompt
+        def prompt
+          <<~PROMPT
+            🔍 Ambiguous Notation Detected
+
+            Ambiguous symbol: "#{@ambiguous_text}"
+            Context: #{@context}
+
+            Please select the correct interpretation:
+          PROMPT
+        end
+
+        # Generate options for clarification
+        #
+        # @return [Array<Hash>] option choices
+        def options
+          @alternatives.map.with_index do |alt, idx|
+            {
+              value: "option_#{idx}",
+              label: alt,
+              description: "Interpret as: #{alt}"
+            }
+          end
+        end
+
+        # Set user's clarification decision
+        #
+        # @param decision [String] selected option (option_0, option_1, etc)
+        def set_decision(decision)
+          index = decision.match(/option_(\d+)/)[1].to_i
+          unless index >= 0 && index < @alternatives.length
+            raise ArgumentError, "Invalid decision: #{decision}"
+          end
+          @decision = @alternatives[index]
+        end
+
+        # Apply clarification to LaTeX
+        #
+        # @return [String] corrected LaTeX
+        def apply_clarification
+          raise "No decision set" unless @decision
+
+          # Simple replacement (in real implementation, would be more sophisticated)
+          corrected = @context.dup
+
+          case @decision
+          when /0 \(zero\)/
+            corrected.gsub!(/O/, '0')
+          when /O \(letter O\)/
+            corrected.gsub!(/0/, 'O')
+          when /1 \(one\)/
+            corrected.gsub!(/[lI]/, '1')
+          when /l \(lowercase L\)/
+            corrected.gsub!(/[1I]/, 'l')
+          # Add more transformations as needed
+          end
+
+          corrected
+        end
+
+        # Convert to MCP elicitation request
+        #
+        # @return [Hash] MCP-compatible request
+        def to_mcp_request
+          {
+            type: 'select',
+            prompt: prompt,
+            field_name: 'ambiguity_clarification',
+            options: options.map { |o| { value: o[:value], label: o[:label] } },
+            metadata: {
+              ambiguous_text: @ambiguous_text,
+              context: @context,
+              position: @position
+            }
+          }
+        end
+
+        private
+
+        # Auto-detect possible alternatives based on ambiguous text
+        #
+        # @return [Array<String>] detected alternatives
+        def detect_alternatives
+          # Check common patterns
+          AMBIGUOUS_PATTERNS.each do |key, pattern_data|
+            if pattern_data[:pattern].match?(@ambiguous_text)
+              return pattern_data[:alternatives]
+            end
+          end
+
+          # Default: generic ambiguity
+          [
+            "Interpretation A: #{@ambiguous_text}",
+            "Interpretation B: similar symbol",
+            "Keep as-is: #{@ambiguous_text}"
+          ]
+        end
+      end
+    end
+  end
+end