hitch-rails 0.2.0

data/lib/hitch/dynamic_registration_rate_limit.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "openssl"
+
+module Hitch
+  # Private fixed-window guard for unauthenticated client registration. It
+  # counts through the host application's own cache store; see
+  # Hitch::RateLimitStore.
+  class DynamicRegistrationRateLimit
+    class Unavailable < StandardError; end
+
+    class Exceeded < StandardError
+      attr_reader :retry_after
+
+      def initialize(retry_after)
+        @retry_after = retry_after
+        super("dynamic client registration rate limit exceeded")
+      end
+    end
+
+    SETTING = "config.dynamic_client_registration_rate_store"
+
+    class << self
+      def check!(remote_ip:)
+        configuration = Hitch.configuration
+        limit = configuration.dynamic_client_registration_limit
+        count = increment(
+          configuration.dynamic_client_registration_rate_store,
+          key_for(remote_ip),
+          limit.fetch(:within)
+        )
+        # A store that cannot count returns nil, the way Rails' :null_store
+        # does. Unlike MCP request admission, which sits behind a bearer token,
+        # registration is unauthenticated: an uncountable store in production
+        # would let anyone create unlimited clients, so refuse rather than
+        # admit. Production also refuses such stores at boot; this is the
+        # second lock on an unauthenticated write.
+        if count.nil?
+          raise Unavailable, "#{SETTING} cannot count registration attempts" if Rails.env.production?
+
+          return true
+        end
+        raise Exceeded, limit.fetch(:within) if count > limit.fetch(:to)
+
+        true
+      end
+
+      private
+
+      def increment(store, key, expires_in)
+        count = store.increment(key, 1, expires_in: expires_in)
+        return if count.nil?
+        raise Unavailable, "DCR rate store returned an invalid count" unless count.is_a?(Integer)
+
+        count
+      rescue Unavailable
+        raise
+      # NotImplementedError (a ScriptError): raised by the base
+      # ActiveSupport::Cache::Store#increment when a store never overrode it.
+      rescue NotImplementedError, StandardError
+        raise Unavailable, "DCR rate store increment failed"
+      end
+
+      def key_for(remote_ip)
+        normalized_ip = IPAddr.new(remote_ip.to_s).to_s
+        secret = Rails.application.secret_key_base.to_s
+        digest = OpenSSL::HMAC.hexdigest("SHA256", secret, normalized_ip)
+        "hitch:dcr:ip:#{digest}"
+      rescue IPAddr::InvalidAddressError
+        raise Unavailable, "DCR request IP could not be normalized"
+      end
+    end
+  end
+end

data/lib/hitch/engine.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Hitch
+  class Engine < ::Rails::Engine
+    isolate_namespace Hitch
+
+    class << self
+      def doctor_command?
+        ARGV.reject { |argument| argument.start_with?("-") } == [ "hitch:doctor" ]
+      end
+    end
+
+    initializer "hitch.zeitwerk_inflections", before: :set_autoloaders do
+      Rails.autoloaders.main.inflector.inflect(
+        "mcp" => "MCP",
+        "sdk_adapter" => "SDKAdapter"
+      )
+    end
+
+    # Rack::MethodOverride would otherwise parse OAuth form bodies before the
+    # controller-level strict admission boundary can cap or redact them.
+    # Anchored to ActionDispatch::Executor because it is present in both the
+    # full and api_only stacks (Rack::MethodOverride is not) and sits upstream
+    # of every body-reading middleware.
+    initializer "hitch.guard_oauth_forms", before: :build_middleware_stack do |app|
+      app.middleware.insert_after ActionDispatch::Executor, Hitch::RackFormGuard
+    end
+
+    # Host apps see the engine's migrations via db:migrate without needing
+    # to copy them — the install generator only writes the initializer.
+    initializer :append_migrations do |app|
+      next if app.root.to_s == root.to_s
+      # Skipped when ENGINE_ROOT is defined, which means the process was
+      # driven through `rails/tasks/engine.rake` — this gem's own
+      # Rakefile, never a host app's. ActiveRecord's own db:load_config
+      # hook (activerecord/railtie.rb) then appends the engine's
+      # db/migrate to DatabaseTasks.migrations_paths with `+=`, no
+      # dedupe. Contributing it here as well puts the directory in that
+      # collection twice, and ActiveRecord::Schema.define raises
+      # "Duplicate migration" as it walks them.
+      #
+      # Latent until a schema is actually reloaded — which is to say
+      # until someone adds a migration, at which point every subsequent
+      # one hits it.
+      next if defined?(ENGINE_ROOT)
+
+      config.paths["db/migrate"].expanded.each do |path|
+        app.config.paths["db/migrate"] << path
+      end
+    end
+
+    # CIMD leans on Rails.cache for negative caching, which is what stops
+    # a dead or hostile client_id buying an outbound request per inbound
+    # one. A NullStore retains nothing between requests, so that guard is
+    # silently absent — precisely on the deployment that thinks it is
+    # protected.
+    #
+    # The concurrency cap and the per-principal rate limit are both
+    # in-process and unaffected, which is why this warns rather than
+    # refuses.
+    # after :load_config_initializers, not :initialize_cache — the host's
+    # config/initializers/hitch.rb is what enables CIMD, so running any
+    # earlier would read the disabled default and never warn.
+    initializer "hitch.warn_on_uncacheable_cimd", after: :load_config_initializers do
+      next unless Hitch.configuration.client_id_metadata_enabled
+      # Production only. :null_store is Rails' default in test, and in
+      # development without tmp/caching-dev.txt, so warning everywhere
+      # would fire on every console, rake task and test run — training
+      # adopters to silence it in the one environment it matters.
+      next unless Rails.env.production?
+      next unless defined?(ActiveSupport::Cache::NullStore)
+      next unless Rails.cache.is_a?(ActiveSupport::Cache::NullStore)
+
+      Rails.logger&.warn(
+        "[hitch] client_id_metadata_enabled is on but Rails.cache is a NullStore. " \
+        "Client metadata documents will be refetched on every authorize request, and " \
+        "negative caching will not limit a dead or hostile client_id. The concurrency " \
+        "cap and per-principal rate limit are unaffected. Configure a real cache store."
+      )
+    end
+
+    initializer "hitch.validate_dynamic_client_registration", after: :load_config_initializers do
+      configuration = Hitch.configuration
+      next unless configuration.dynamic_client_registration_enabled
+      next if Hitch::Engine.doctor_command?
+
+      unless configuration.dynamic_client_registration_enabled_configured?
+        Rails.logger&.warn(
+          "[hitch] Dynamic Client Registration is enabled by the compatibility default. " \
+          "Set config.dynamic_client_registration_enabled explicitly. Production requires " \
+          "the registration rate store (config.dynamic_client_registration_rate_store, " \
+          "default: your cache store) to count across processes; new installs disable DCR."
+        )
+      end
+
+      next unless Rails.env.production?
+
+      Hitch::RateLimitStore.assert_shared!(
+        configuration.dynamic_client_registration_rate_store,
+        setting: Hitch::DynamicRegistrationRateLimit::SETTING
+      )
+    end
+
+    initializer "hitch.validate_configuration", after: :load_config_initializers do
+      # A fresh host has to boot once to run this generator, and the
+      # initializer it creates is what sets resource_uri. Keep the exception
+      # exact: other generators and every ordinary application boot still
+      # validate and fail closed.
+      install_generator = ARGV.first == "hitch:install" ||
+        (%w[generate g].include?(ARGV.first) && ARGV[1] == "hitch:install")
+      next if install_generator || Hitch::Engine.doctor_command?
+
+      Hitch.configuration.validate!
+    end
+
+    config.to_prepare do
+      configuration = Hitch.configuration
+      next if Hitch::Engine.doctor_command?
+      next unless configuration.resource_uri.present?
+      next unless configuration.mcp.enabled
+
+      configuration.mcp.validate!
+
+      configuration.mcp.prepare_registry!(supported_scopes: configuration.supported_scopes)
+      # Forces server_info normalization so a malformed value fails here,
+      # alongside registry validation, rather than on the first request.
+      configuration.mcp.server_info
+      configuration.mcp.validate_rate_limit_store!
+    end
+
+    # Filter OAuth secrets out of Rails request logs. Without this, a
+    # crash on /oauth/token would log the raw code + code_verifier
+    # (both lookup credentials), and a successful response would log
+    # the issued access_token. None should ever appear in logs.
+    #
+    # :token is included because POST /oauth/revoke receives the live
+    # bearer token in params[:token] (RFC 7009) — without filtering it,
+    # the gem's own revoke endpoint would log usable access tokens. The
+    # filter matches param names, so a host's unrelated :token params
+    # are also redacted from logs; for a secret-bearing name that is the
+    # safe default, not a regression.
+    initializer "hitch.filter_parameters" do |app|
+      app.config.filter_parameters += [
+        :code,
+        :code_verifier,
+        :client_secret,
+        :client_secret_digest,
+        :access_token,
+        :authorization_code,
+        :token
+      ]
+    end
+  end
+end

data/lib/hitch/mcp/configuration.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    class Configuration
+      DEFAULT_MAX_REQUEST_BYTES = 1_048_576
+      DEFAULT_MAX_RESULT_BYTES = 1_048_576
+      DEFAULT_REQUEST_LIMIT = { to: 120, within: 60 }.freeze
+      SETTING = "mcp.rate_limit_store"
+
+      attr_reader :enabled, :registry, :scope_resolver, :request_limit,
+        :max_request_bytes, :max_result_bytes
+
+      def initialize
+        @enabled = false
+        @registry = nil
+        @registry_snapshot = nil
+        @registry_mutex = Mutex.new
+        @server_info = nil
+        @normalized_server_info = nil
+        @scope_resolver = nil
+        @request_limit = DEFAULT_REQUEST_LIMIT
+        @rate_limit_store = nil
+        @max_request_bytes = DEFAULT_MAX_REQUEST_BYTES
+        @max_result_bytes = DEFAULT_MAX_RESULT_BYTES
+      end
+
+      # The one explicit switch for the authenticated /mcp endpoint runtime.
+      def enabled=(value)
+        unless value == true || value == false
+          raise ArgumentError, "mcp.enabled must be true or false"
+        end
+
+        @enabled = value
+      end
+
+      def registry=(value)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, "mcp.registry must be a nonempty String constant name"
+        end
+
+        @registry_mutex.synchronize do
+          @registry = value.dup.freeze
+          @registry_snapshot = nil
+        end
+        @registry
+      end
+
+      # Returns the validated, frozen, string-keyed identity hash. Normalized
+      # lazily so the reloadable validator constant is only touched after
+      # boot; the engine's to_prepare hook forces this read, so a malformed
+      # value fails the boot rather than the first request.
+      def server_info
+        @normalized_server_info ||= Hitch::MCP::Internal::ServerInfo.normalize(
+          @server_info || {
+            "name" => Rails.application.class.module_parent_name.underscore.dasherize,
+            "version" => "1.0.0"
+          }
+        )
+      end
+
+      def server_info=(value)
+        unless value.nil? || value.is_a?(Hash)
+          raise ArgumentError, "mcp.server_info must be a Hash"
+        end
+
+        # New value first: a reader interleaving between these two writes
+        # re-memoizes at worst the NEW value, never pins the old one.
+        @server_info = value
+        @normalized_server_info = nil
+      end
+
+      def scope_resolver=(value)
+        unless value.nil? || value.respond_to?(:call)
+          raise ArgumentError, "mcp.scope_resolver must be callable"
+        end
+
+        @scope_resolver = value
+      end
+
+      def request_limit=(value)
+        @request_limit = normalize_request_limit(value)
+      end
+
+      # Nil means "whatever this application already configured", which is what
+      # ActionController::RateLimiting does. Hosts that want MCP admission kept
+      # out of their general cache pass their own ActiveSupport::Cache store.
+      def rate_limit_store=(value)
+        @rate_limit_store = Hitch::RateLimitStore.validate!(value, setting: SETTING)
+      end
+
+      def rate_limit_store
+        Hitch::RateLimitStore.resolve(@rate_limit_store)
+      end
+
+      def max_request_bytes=(value)
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError, "mcp.max_request_bytes must be a positive integer"
+        end
+
+        @max_request_bytes = value
+      end
+
+      def max_result_bytes=(value)
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError, "mcp.max_result_bytes must be a positive integer"
+        end
+
+        @max_result_bytes = value
+      end
+
+      def validate!
+        return true unless enabled
+
+        unless registry.is_a?(String) && !registry.empty?
+          raise ArgumentError, "mcp.registry is required when mcp.enabled is true"
+        end
+
+        true
+      end
+
+      # Resolved separately from validate! because the application's cache store
+      # is assembled by Rails' own initializers; this runs from to_prepare, once
+      # config.cache_store is settled.
+      def validate_rate_limit_store!
+        return true unless Rails.env.production?
+
+        Hitch::RateLimitStore.assert_shared!(rate_limit_store, setting: SETTING)
+      end
+
+      # Framework lifecycle, not a host knob: the engine's to_prepare hook
+      # rebuilds the snapshot; the endpoint reads it per request.
+      def prepare_registry!(supported_scopes:)
+        @registry_mutex.synchronize do
+          @registry_snapshot = nil
+          @registry_snapshot = Hitch::MCP::Internal::RegistryRuntime.build_snapshot(
+            registry_name: @registry,
+            supported_scopes:
+          )
+        end
+      end
+
+      def registry_snapshot!
+        @registry_mutex.synchronize do
+          @registry_snapshot || raise(ArgumentError, "MCP registry is unavailable")
+        end
+      end
+
+      private
+
+      def normalize_request_limit(value)
+        unless value.respond_to?(:to_h)
+          raise ArgumentError, "mcp.request_limit must contain :to and :within"
+        end
+
+        # Duplicate keys across spellings ({ to: 1, "to" => 2 }) produce a
+        # third key and fail the comparison.
+        mapping = value.to_h
+        unless mapping.keys.map(&:to_s).sort == %w[to within]
+          raise ArgumentError, "mcp.request_limit must contain only :to and :within"
+        end
+
+        to = mapping[:to] || mapping["to"]
+        unless to.is_a?(Integer) && to.positive?
+          raise ArgumentError, "mcp.request_limit[:to] must be a positive Integer"
+        end
+
+        within = positive_duration_seconds(mapping[:within] || mapping["within"])
+        { to:, within: }.freeze
+      rescue NoMethodError, TypeError
+        raise ArgumentError, "mcp.request_limit must contain only :to and :within"
+      end
+
+      def positive_duration_seconds(value)
+        seconds = if defined?(ActiveSupport::Duration) && value.is_a?(ActiveSupport::Duration)
+          float = value.to_f
+          value.to_i if float.finite? && float == value.to_i
+        elsif value.is_a?(Integer)
+          value
+        end
+        unless seconds&.positive?
+          raise ArgumentError,
+            "mcp.request_limit[:within] must be a positive whole number of seconds or ActiveSupport::Duration"
+        end
+
+        seconds
+      end
+    end
+  end
+end

data/lib/hitch/mcp/protocol.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    # The MCP protocol vocabulary: the one place that says which version
+    # Hitch speaks, which methods it answers, and what a tool may be named.
+    #
+    # Plain Ruby in lib rather than app/models, because the public test
+    # helper reads it at require time, before Rails has booted.
+    module Protocol
+      VERSION = "2026-07-28"
+
+      # Every JSON-RPC method the endpoint answers. Anything else is -32601
+      # before the SDK is built.
+      METHODS = %w[server/discover tools/list tools/call].freeze
+
+      # The wire name of a tool, and the shape any tool name must have before
+      # it may appear in a telemetry payload or an error report.
+      MAX_TOOL_NAME_LENGTH = 64
+      TOOL_NAME = /\A[A-Za-z0-9_.-]{1,#{MAX_TOOL_NAME_LENGTH}}\z/
+
+      # The only tool failure text that reaches a client when the host did
+      # not author one itself.
+      GENERIC_TOOL_ERROR = "Tool execution failed"
+
+      module_function
+
+      # instance_of?, not is_a?: a String subclass can override the methods
+      # every downstream reader calls, and a tool name reaches telemetry and
+      # error reports.
+      def tool_name?(value)
+        value.instance_of?(String) && TOOL_NAME.match?(value)
+      end
+    end
+  end
+end

data/lib/hitch/mcp/test_helper.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "base64"
+require "date"
+require "digest"
+require "json"
+require "securerandom"
+require "uri"
+require "hitch/mcp/protocol"
+
+module Hitch
+  module MCP
+    module TestHelper
+      # Public: host test suites pin this.
+      PROTOCOL_VERSION = Protocol::VERSION
+
+      TOKEN_PATTERN = /\A[A-Za-z0-9\-._~+\/]+=*\z/
+
+      def mcp_headers(token:, method:, name: nil, protocol_version: PROTOCOL_VERSION)
+        resource = mcp_test_resource_uri!
+        mcp_test_headers(
+          resource:,
+          token:,
+          method:,
+          name:,
+          protocol_version:
+        )
+      end
+
+      def post_mcp(method:, token:, params: {}, id: "hitch-test", client_info: nil,
+        capabilities: {}, protocol_version: PROTOCOL_VERSION)
+        resource = mcp_test_resource_uri!
+        mcp_test_match_scheme!(resource)
+        normalized_params = mcp_test_json_hash(params, "params")
+        raise ArgumentError, "params must not supply _meta" if normalized_params.key?("_meta")
+
+        normalized_capabilities = mcp_test_json_hash(capabilities, "capabilities")
+        normalized_client_info = if client_info.nil?
+          nil
+        else
+          mcp_test_json_hash(client_info, "client_info")
+        end
+        normalized_id = mcp_test_id(id)
+        name = normalized_params["name"] if method == "tools/call"
+        metadata = {
+          "io.modelcontextprotocol/protocolVersion" => protocol_version.to_s,
+          "io.modelcontextprotocol/clientCapabilities" => normalized_capabilities
+        }
+        if normalized_client_info
+          metadata["io.modelcontextprotocol/clientInfo"] = normalized_client_info
+        end
+        normalized_params["_meta"] = metadata
+        body = JSON.generate(
+          "jsonrpc" => "2.0",
+          "id" => normalized_id,
+          "method" => method,
+          "params" => normalized_params
+        )
+
+        post resource.request_uri,
+          params: body,
+          headers: mcp_test_headers(
+            resource:,
+            token:,
+            method:,
+            name:,
+            protocol_version:
+          )
+        response
+      rescue JSON::GeneratorError, EncodingError => error
+        raise ArgumentError, "MCP test request is not valid JSON: #{error.class}"
+      end
+
+      # Mints a real access token through the production authorization-code
+      # path (create_authorization! + PKCE exchange) and returns the raw
+      # bearer token post_mcp expects. The principal is any persisted record
+      # the host treats as the signed-in user.
+      def mint_mcp_token(principal:, scopes: Hitch.configuration.supported_scopes,
+        client_id: "hitch-test-client")
+        scopes = Array(scopes)
+        unsupported = scopes - Hitch.configuration.supported_scopes
+        unless unsupported.empty?
+          # The real flow clamps grants to supported_scopes; minting past it
+          # would let a test pass against a grant production can never issue.
+          raise ArgumentError,
+            "scopes are not in Hitch.configuration.supported_scopes: #{unsupported.join(' ')}"
+        end
+
+        verifier = SecureRandom.urlsafe_base64(64)
+        challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+        resource_uri = Hitch.configuration.resource_uri
+        authorization = Hitch::AccessToken.create_authorization!(
+          principal: principal,
+          client_id: client_id,
+          client_name: client_id,
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scopes: scopes.join(" "),
+          resource_uri: resource_uri
+        )
+        Hitch::AccessToken.exchange_authorization_code!(
+          raw_code: authorization.raw_authorization_code,
+          code_verifier: verifier,
+          client_id: client_id,
+          resource_uri: resource_uri
+        ).fetch(:raw_token)
+      end
+
+      private
+
+      def mcp_test_resource_uri!
+        value = Hitch.configuration.resource_uri
+        raise ArgumentError, "Hitch resource_uri must be configured" unless value.is_a?(String)
+
+        resource = URI.parse(value)
+        unless %w[http https].include?(resource.scheme) && resource.host && !resource.fragment
+          raise ArgumentError, "Hitch resource_uri must be an absolute HTTP URI"
+        end
+
+        resource
+      rescue URI::InvalidURIError
+        raise ArgumentError, "Hitch resource_uri must be an absolute HTTP URI"
+      end
+
+      # The endpoint binds to the canonical resource_uri exactly — scheme
+      # included — and an integration test speaks http unless told otherwise.
+      # A host whose resource_uri is https therefore got a 400 with an empty
+      # body and nothing in the log, for want of one `https!`. The helper
+      # already derives the Host from resource_uri; it derives the scheme
+      # from it too.
+      def mcp_test_match_scheme!(resource)
+        return unless respond_to?(:https!)
+
+        https!(resource.scheme == "https")
+      end
+
+      def mcp_test_headers(resource:, token:, method:, name:, protocol_version:)
+        mcp_test_validate_token!(token)
+        mcp_test_validate_method_and_name!(method, name)
+        mcp_test_validate_protocol_version!(protocol_version)
+
+        {
+          "Host" => Hitch::ResourceUri.authority(resource),
+          "Authorization" => "Bearer #{token}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json, text/event-stream",
+          "MCP-Protocol-Version" => protocol_version,
+          "Mcp-Method" => method
+        }.tap do |headers|
+          headers["Mcp-Name"] = name if name
+        end
+      end
+
+      def mcp_test_validate_token!(token)
+        return if token.is_a?(String) && token.bytesize.between?(1, 4_096) &&
+          TOKEN_PATTERN.match?(token)
+
+        raise ArgumentError, "token must be a bounded bearer token"
+      end
+
+      def mcp_test_validate_method_and_name!(method, name)
+        raise ArgumentError, "method is not a supported Hitch MCP method" unless
+          Protocol::METHODS.include?(method)
+
+        if method == "tools/call"
+          raise ArgumentError, "name is required for tools/call" unless
+            Protocol.tool_name?(name)
+        elsif !name.nil?
+          raise ArgumentError, "name is only valid for tools/call"
+        end
+      end
+
+      def mcp_test_validate_protocol_version!(protocol_version)
+        raise ArgumentError, "protocol_version must be an ISO date" unless
+          protocol_version.is_a?(String) && protocol_version.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        Date.iso8601(protocol_version)
+      rescue Date::Error
+        raise ArgumentError, "protocol_version must be an ISO date"
+      end
+
+      def mcp_test_id(id)
+        return id.dup if id.is_a?(String) && !id.empty?
+        return id if id.is_a?(Integer)
+
+        raise ArgumentError, "id must be a nonempty String or Integer"
+      end
+
+      # A generate/parse round trip is the JSON normalizer: symbol keys
+      # become strings, structures are deep-copied so the caller's hash is
+      # never mutated, and cycles or non-finite numbers raise.
+      def mcp_test_json_hash(value, label)
+        raise ArgumentError, "#{label} must be a Hash" unless value.is_a?(Hash)
+
+        JSON.parse(JSON.generate(value))
+      rescue JSON::JSONError
+        raise ArgumentError, "#{label} is not plain JSON data"
+      end
+
+      private_constant :TOKEN_PATTERN
+    end
+  end
+end

data/lib/hitch/pkce.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hitch
+  module Pkce
+    S256_CHALLENGE = /\A[A-Za-z0-9_-]{43}\z/
+    VERIFIER = /\A[A-Za-z0-9\-._~]{43,128}\z/
+
+    module_function
+
+    def valid_s256_challenge?(value)
+      value.is_a?(String) && value.match?(S256_CHALLENGE)
+    end
+
+    def valid_verifier?(value)
+      value.is_a?(String) && value.match?(VERIFIER)
+    end
+  end
+end