hitch-rails 0.2.0

data/SECURITY.md

@@ -0,0 +1,118 @@
+# Security Policy
+
+hitch-rails is an OAuth 2.1 **authorization server**. A defect here can
+expose an adopter's user accounts and every MCP tool their server
+exposes, so security reports get priority over everything else in this
+project.
+
+## Supported versions
+
+The gem is pre-1.0. Security fixes land on `main` and ship in the next
+release; only the latest release line is supported.
+
+| Version | Supported |
+| ------- | --------- |
+| latest 0.2.x release, and `main` | ✅ |
+
+The supported runtime matrix is Ruby `>= 3.3, < 4.1`, Rails `>= 8.0, < 9`,
+and SQLite or PostgreSQL. Reports that reproduce only on an unsupported
+runtime, adapter, or client version may still reveal a real bug, but the
+maintainer will first confirm them on that matrix.
+
+## Reporting a vulnerability
+
+**Do not open a public issue for a suspected vulnerability.**
+
+Use GitHub's private vulnerability reporting:
+[Security → Report a vulnerability](https://github.com/tylerklose/hitch-rails/security/advisories/new).
+It's private to the maintainers, keeps the discussion attached to the
+repository, and handles advisory publication and credit at the end.
+
+If you can't use it, open a public issue that asks for a private channel
+and **contains no details of the finding** — a maintainer will follow up
+from there.
+
+Helpful to include, in whatever detail you have:
+
+- The affected endpoint or class, ideally with a `file.rb:line` reference
+- A request sequence that reproduces it
+- What an attacker gains — token theft, account takeover, scope
+  escalation, authorization bypass
+- The gem version or commit SHA, and Rails version
+
+### What to expect
+
+This is maintained by one person, so the honest commitment is modest and
+kept rather than ambitious and missed:
+
+- **Acknowledgement** within 5 business days
+- **Assessment** — whether it's confirmed, and a rough severity — within
+  10 business days
+- **Coordinated disclosure.** A fix lands on `main` and an advisory is
+  published together. Reporters are credited unless they'd rather not be.
+
+There is no bug bounty.
+
+## Scope
+
+### In scope
+
+The authorization substrate the gem owns:
+
+- Token issuance, validation, expiry, and revocation
+  (`Hitch::AccessToken`)
+- PKCE verification and authorization-code single-use enforcement
+- `redirect_uri` validation and matching (`Hitch::UriValidation`)
+- RFC 8707 audience binding — a token accepted for the wrong resource
+- Dynamic Client Registration — client impersonation, registration
+  poisoning, strict JSON admission, bounded metadata, mode enforcement, and
+  shared-store rate limiting
+- Discovery metadata (`/.well-known/*`) — issuer or endpoint
+  manipulation. The issuer is fixed by `config.resource_uri`; accepted ingress
+  aliases and forwarded headers cannot select it.
+- Pre-instrumentation size, shape, duplicate-parameter, and secret-redaction
+  boundaries on authorize, token, revoke, and registration requests
+- Consent-screen CSRF, clickjacking, or scope escalation
+- CORS policy in `Hitch::CorsSupport`
+- `Hitch::MCP::Endpoint` Host/Origin/method/authentication ordering, canonical
+  protected-resource challenge, media/header validation, raw body cap,
+  duplicate-member rejection, reserved argument handling, callback isolation,
+  fleet-shared authenticated admission, structural notification redaction, and
+  stable error sanitization
+- `hitch:doctor` output redaction, admission-store probe isolation/expiry/cleanup, and
+  its guarantee not to mutate application data or repair host configuration
+
+### Out of scope
+
+- **The host application's tool implementation and business policy.** Report
+  tool-level authorization bugs to the application. Authentication, admission,
+  discovery challenges, and response shaping supplied by
+  `Hitch::MCP::Endpoint` remain Hitch's responsibility and are in scope.
+- **Documented adopter misconfiguration.** The README's *Adopter security
+  requirements* section lists the host settings the gem depends on
+  (`allowed_hosts`, `allowed_origins`, CSRF on the consent path,
+  `resource_uri`, `trusted_proxies`, and a shared DCR store when DCR is
+  enabled in production). A report that "a host ignoring these is
+  exploitable" describes known, documented behavior.
+
+  A report that **following them is still insufficient** is very much in
+  scope — that's a gem bug, and a valuable one.
+- Vulnerabilities in Rails or other dependencies, unless hitch-rails uses
+  them in a way that creates exposure the upstream project doesn't have.
+
+## Spec-conformance gaps are not vulnerabilities
+
+This project tracks the MCP specification closely, and a gap between what
+the spec requires and what the gem implements is usually a **public
+issue**, not a security report.
+
+Example: local HTTP development emits the RFC 9207 `iss` parameter so the
+security path is exercised, but does not advertise support because RFC 9207
+requires an HTTPS issuer. That deliberate development exception is a public
+conformance limitation, not a production security promise.
+
+The line: if exploiting it requires only a client that talks to this
+server, report it privately. If it's "this doesn't match the spec text,"
+open an issue and cite the section. When you're unsure which it is,
+report privately — the cost of being wrong in that direction is a
+redirect to the issue tracker.

data/app/controllers/concerns/hitch/cors_support.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Exact-origin CORS support for Hitch endpoints and host controllers that
+  # opt in. Preflight is validated separately from ordinary response headers.
+  module CorsSupport
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :handle_hitch_preflight, if: -> { request.options? }
+      before_action :set_cors_headers, unless: -> { request.options? }
+    end
+
+    private
+
+    ALLOWED_REQUEST_HEADERS = [
+      "Content-Type",
+      "Authorization",
+      "MCP-Protocol-Version",
+      "Mcp-Method",
+      "Mcp-Name"
+    ].freeze
+
+    LOOPBACK_PATTERN = %r{\Ahttps?://(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?\z}.freeze
+
+    def set_cors_headers
+      append_vary_header("Origin")
+      origin = request.headers["Origin"]
+      return unless allowed_origin?(origin)
+
+      response.headers["Access-Control-Allow-Origin"] = origin
+    end
+
+    def allowed_origin?(origin)
+      return false unless origin.is_a?(String)
+      return true if Hitch.configuration.allowed_origins.include?(origin)
+
+      loopback_origins_allowed? && LOOPBACK_PATTERN.match?(origin)
+    end
+
+    # Called by Hitch::PreflightsController. Host-owned endpoints may call the
+    # same private helper from an explicit action, keeping route ownership clear.
+    def hitch_preflight(allowed_methods:)
+      append_vary_header("Origin")
+      append_vary_header("Access-Control-Request-Method")
+      append_vary_header("Access-Control-Request-Headers")
+
+      origin = request.headers["Origin"]
+      requested_method = request.headers["Access-Control-Request-Method"].to_s.upcase
+      methods = Array(allowed_methods).map { |method| method.to_s.upcase }.uniq
+      requested_headers = parsed_requested_headers
+
+      unless allowed_origin?(origin) && methods.include?(requested_method) && requested_headers_allowed?(requested_headers)
+        return head :forbidden
+      end
+
+      response.headers["Access-Control-Allow-Origin"] = origin
+      response.headers["Access-Control-Allow-Methods"] = methods.join(", ")
+      response.headers["Access-Control-Allow-Headers"] = ALLOWED_REQUEST_HEADERS.join(", ")
+      response.headers["Access-Control-Max-Age"] = "600"
+      head :no_content
+    end
+
+    def handle_hitch_preflight
+      methods = request.path_parameters[:target_methods].to_s.split(",").reject(&:empty?)
+      methods = [ "POST" ] if methods.empty?
+      hitch_preflight(allowed_methods: methods)
+    end
+
+    def parsed_requested_headers
+      raw = request.headers["Access-Control-Request-Headers"].to_s
+      return [] if raw.empty?
+
+      values = raw.split(",", -1).map(&:strip)
+      return nil if values.any?(&:empty?)
+
+      values
+    end
+
+    def requested_headers_allowed?(headers)
+      return false if headers.nil?
+
+      allowed = ALLOWED_REQUEST_HEADERS.map(&:downcase)
+      headers.all? { |header| allowed.include?(header.downcase) }
+    end
+
+    def loopback_origins_allowed?
+      Rails.env.local?
+    end
+
+    def append_vary_header(value)
+      values = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+      values << value unless values.include?(value)
+      response.headers["Vary"] = values.join(", ")
+    end
+  end
+end

data/app/controllers/concerns/hitch/host_validation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  # Rejects an untrusted request origin before an engine endpoint derives
+  # issuer URLs, parses OAuth credentials, or performs registration work.
+  module HostValidation
+    extend ActiveSupport::Concern
+
+    included do
+      # This must precede host authentication and every callback that can
+      # derive a public URL from the request. `prepend` keeps that ordering
+      # even when a host includes Hitch into a controller that already has
+      # application-wide before_actions.
+      prepend_before_action :require_allowed_hitch_host!
+    end
+
+    private
+
+    def require_allowed_hitch_host!
+      return if hitch_request_origin_allowed?
+
+      render json: {
+        error: "invalid_request",
+        error_description: "Request origin is not allowed"
+      }, status: :bad_request
+    end
+
+    def hitch_request_origin_allowed?
+      request_host = request.hostname.to_s.downcase
+      return false if request_host.empty?
+
+      resource = URI.parse(Hitch.configuration.resource_uri.to_s)
+      hitch_allowed_hosts(resource).include?(request_host) &&
+        request.scheme == resource.scheme &&
+        request.port == resource.port
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def hitch_allowed_hosts(resource = URI.parse(Hitch.configuration.resource_uri.to_s))
+      explicit_hosts = Hitch.configuration.allowed_hosts
+      canonical_host = resource.hostname&.downcase
+
+      [ canonical_host, *explicit_hosts ].compact.uniq
+    rescue URI::InvalidURIError
+      explicit_hosts
+    end
+  end
+end

data/app/controllers/concerns/hitch/issuer_url.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  # The authorization server's issuer identifier (RFC 8414 §2).
+  #
+  # Shared because it MUST be byte-identical everywhere it appears. The
+  # discovery document advertises it as `issuer`; the authorization response
+  # carries it as `iss` (RFC 9207); bearer challenges point back to it. Clients
+  # compare these values exactly.
+  #
+  # The issuer is the fixed origin of the canonical resource_uri. It never
+  # comes from Host or Forwarded headers. `allowed_hosts` are ingress aliases,
+  # not alternate issuer identities; every accepted alias advertises this same
+  # canonical origin.
+  module IssuerUrl
+    extend ActiveSupport::Concern
+
+    private
+
+    def issuer_url
+      Hitch::ResourceUri.origin(URI.parse(Hitch.configuration.resource_uri.to_s))
+    end
+  end
+end

data/app/controllers/concerns/hitch/mcp/endpoint.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hitch
+  module MCP
+    # Authenticated, stateless MCP 2026-07-28 JSON endpoint for a dedicated
+    # host-owned ActionController::API controller.
+    module Endpoint
+      extend ActiveSupport::Concern
+
+      include Hitch::RequestAdmission
+
+      included do
+        skip_forgery_protection if respond_to?(:skip_forgery_protection)
+
+        prepend_before_action :hitch_mcp_gate!, only: :handle
+        prepend_around_action :hitch_mcp_observe_request,
+          only: :handle,
+          unless: -> { request.options? }
+      end
+
+      def handle
+        unless Internal::MediaType.json_content_type?(request.get_header("CONTENT_TYPE"))
+          hitch_mcp_explain!("Content-Type must be exactly application/json")
+          return hitch_mcp_protocol_error!(415, -32600, "Invalid Request")
+        end
+        unless Internal::MediaType.accepts_required_types?(request.get_header("HTTP_ACCEPT"))
+          hitch_mcp_explain!("Accept must admit both application/json and text/event-stream")
+          return hitch_mcp_protocol_error!(406, -32600, "Invalid Request")
+        end
+
+        max_request_bytes = Hitch.configuration.mcp.max_request_bytes
+        raw_body = hitch_read_bounded_request_body(max_request_bytes)
+        @hitch_mcp_observation&.request_bytes!(raw_body ? raw_body.bytesize : max_request_bytes + 1)
+        unless raw_body
+          hitch_mcp_explain!("request body exceeds mcp.max_request_bytes (#{max_request_bytes})")
+          return hitch_mcp_protocol_error!(413, -32600, "Invalid Request")
+        end
+
+        verified_request = Internal::VerifiedRequest.call(
+          raw_body: raw_body,
+          headers: {
+            protocol_version: request.get_header("HTTP_MCP_PROTOCOL_VERSION"),
+            method: request.get_header("HTTP_MCP_METHOD"),
+            name: request.get_header("HTTP_MCP_NAME")
+          }
+        )
+        @hitch_mcp_observation&.verified!(verified_request)
+
+        hitch_mcp_dispatch!(verified_request)
+      rescue Internal::VerifiedRequest::Failure => error
+        # The wire deliberately says only "Invalid params" for a dozen
+        # different rejections. Locally the first backtrace frame names the
+        # exact check that refused, which is the difference between a
+        # developer fixing their request and guessing at it.
+        Internal::LocalDiagnosis.report(
+          "MCP request rejected (#{error.code} #{error.message})", error
+        )
+        hitch_mcp_protocol_error!(
+          error.http_status,
+          error.code,
+          error.message,
+          request_id: error.request_id,
+          data: error.data
+        )
+      rescue StandardError => error
+        request_id = verified_request && verified_request["id"]
+        Internal::EndpointErrorReporter.report(category: :dispatch)
+        Internal::LocalDiagnosis.report("MCP request failed during dispatch", error)
+        hitch_mcp_protocol_error!(200, -32603, "Internal error", request_id: request_id)
+      ensure
+        request.delete_header("RAW_POST_DATA") if request
+      end
+
+      private
+
+      # ActionController instrumentation reads both body parameters and format
+      # before callbacks. Seed safe caches first; Hitch validates the raw body
+      # and Accept header itself after admission.
+      def process_action(action_name, ...)
+        if action_name.to_s == "handle"
+          request.request_parameters = {}
+          request.formats = [ :json ]
+        end
+
+        super
+      end
+
+      def hitch_mcp_observe_request
+        Internal::Observation.with_request_state do |state|
+          @hitch_mcp_observation = state
+          yield
+        end
+      ensure
+        begin
+          hitch_mcp_request_observed!
+        ensure
+          @hitch_mcp_observation = nil
+        end
+      end
+
+      # The security order, top to bottom. Each gate halts the request by
+      # rendering; nothing later runs once one has.
+      def hitch_mcp_gate!
+        hitch_mcp_host_gate!
+        return if performed?
+
+        hitch_mcp_origin_gate!
+        return if performed?
+
+        hitch_mcp_method_gate!
+        return if performed?
+
+        hitch_mcp_authenticate!
+        return if performed?
+
+        hitch_mcp_rate_admission!
+      end
+
+      def hitch_mcp_host_gate!
+        hitch_mcp_append_vary!("Origin")
+        if request.options?
+          hitch_mcp_append_vary!("Access-Control-Request-Method")
+          hitch_mcp_append_vary!("Access-Control-Request-Headers")
+        end
+        return if Internal::HostAuthority.allowed?(request)
+
+        hitch_mcp_explain!(
+          "request does not match the canonical resource_uri " \
+            "(#{Hitch.configuration.resource_uri}) — scheme, host, port, path and query " \
+            "must all match, and an integration test speaks http unless told otherwise"
+        )
+        head :bad_request
+      end
+
+      def hitch_mcp_origin_gate!
+        origin = request.get_header("HTTP_ORIGIN")
+        return hitch_mcp_origin_denied! if request.options? && origin.nil?
+        return if origin.nil?
+        return hitch_mcp_origin_denied! unless Internal::CorsPolicy.origin_allowed?(origin)
+        return if request.options?
+
+        response.headers["Access-Control-Allow-Origin"] = origin
+      end
+
+      def hitch_mcp_method_gate!
+        return hitch_mcp_preflight! if request.options?
+        return if request.post?
+
+        response.headers["Allow"] = "POST, OPTIONS"
+        head :method_not_allowed
+      end
+
+      def hitch_mcp_authenticate!
+        raw_token = Internal::BearerChallenge.token(request.get_header("HTTP_AUTHORIZATION"))
+        return hitch_mcp_unauthorized! unless raw_token
+
+        access_token = Hitch::AccessToken.find_by_token(raw_token)
+        resource = Hitch.configuration.resource_uri
+        client_id = access_token&.client_id
+        valid = access_token&.valid_for_resource?(resource) &&
+          client_id.is_a?(String) && !client_id.empty?
+        return hitch_mcp_unauthorized! unless valid
+
+        principal = hitch_mcp_token_principal(access_token)
+        return hitch_mcp_unauthorized! unless principal
+
+        @hitch_mcp_access_token = access_token
+        @hitch_mcp_principal = principal
+        @hitch_mcp_client_id = client_id.dup.freeze
+        @hitch_mcp_resource = resource.dup.freeze
+        @hitch_mcp_granted_scopes = access_token.scopes.to_s.split.map { |scope| scope.dup.freeze }.freeze
+        @hitch_mcp_observation&.authenticated!(principal:, client_id:)
+      rescue StandardError
+        Internal::EndpointErrorReporter.report(category: :authentication)
+        head :service_unavailable
+      end
+
+      def hitch_mcp_token_principal(access_token)
+        access_token.principal
+      rescue ActiveRecord::RecordNotFound, NameError
+        nil
+      end
+
+      def hitch_mcp_rate_admission!
+        limit = Hitch.configuration.mcp.request_limit
+        count = hitch_mcp_admit_authenticated_request(
+          principal: @hitch_mcp_principal,
+          client_id: @hitch_mcp_client_id
+        )
+        return if count.nil? || count <= limit.fetch(:to)
+
+        response.headers["Retry-After"] = limit.fetch(:within).to_s
+        response.headers["Access-Control-Expose-Headers"] = "Retry-After"
+        head :too_many_requests
+      # NotImplementedError is a ScriptError, not a StandardError: the base
+      # ActiveSupport::Cache::Store#increment raises it, and every subclass
+      # answers respond_to?(:increment), so a store that never overrode it
+      # passes validation and surfaces here.
+      rescue NotImplementedError, StandardError
+        Internal::EndpointErrorReporter.report(category: :request_admission)
+        head :service_unavailable
+      end
+
+      def hitch_mcp_dispatch!(verified_request)
+        scope = hitch_mcp_resolve_scope
+        context = hitch_mcp_context(verified_request, scope:)
+        server_info = Hitch.configuration.mcp.server_info
+
+        snapshot = Hitch.configuration.mcp.registry_snapshot!
+        tools = hitch_mcp_tools(verified_request:, context:, snapshot:)
+        return if performed?
+
+        protocol_response = Internal::SDKAdapter.call(
+          verified_request: verified_request,
+          tools: tools,
+          context: context,
+          server_info: server_info
+        )
+        hitch_mcp_render_protocol!(protocol_response, status: 200)
+      end
+
+      def hitch_mcp_resolve_scope
+        resolver = Hitch.configuration.mcp.scope_resolver
+        return nil unless resolver
+
+        resolver.call(
+          principal: @hitch_mcp_principal,
+          access_token: @hitch_mcp_access_token,
+          request: request
+        )
+      end
+
+      def hitch_mcp_context(verified_request, scope:)
+        metadata = verified_request.fetch("params").fetch("_meta")
+        Context.new(
+          principal: @hitch_mcp_principal,
+          access_token: @hitch_mcp_access_token,
+          scope: scope,
+          granted_scopes: @hitch_mcp_granted_scopes,
+          client_id: @hitch_mcp_client_id,
+          resource: @hitch_mcp_resource,
+          request_id: verified_request.fetch("id"),
+          remote_ip: request.remote_ip,
+          user_agent: request.user_agent,
+          protocol_version: metadata.fetch("io.modelcontextprotocol/protocolVersion"),
+          meta: metadata
+        )
+      end
+
+      def hitch_mcp_protocol_error!(status, code, message, request_id: nil, data: nil)
+        error = { code: code, message: message }
+        error[:data] = data if data
+        hitch_mcp_render_protocol!(
+          { jsonrpc: "2.0", id: request_id, error: error },
+          status: status
+        )
+      end
+
+      def hitch_mcp_render_protocol!(protocol_response, status:)
+        @hitch_mcp_observation&.protocol_response!(protocol_response)
+        render body: JSON.generate(protocol_response), status: status, content_type: "application/json"
+      end
+
+      def hitch_mcp_origin_denied!
+        hitch_mcp_explain!("Origin is not in config.allowed_origins")
+        response.headers.delete("Access-Control-Allow-Origin")
+        head :forbidden
+      end
+
+      def hitch_mcp_preflight!
+        allowed = Internal::CorsPolicy.preflight_allowed?(
+          requested_method: request.get_header("HTTP_ACCESS_CONTROL_REQUEST_METHOD"),
+          requested_headers: request.get_header("HTTP_ACCESS_CONTROL_REQUEST_HEADERS")
+        )
+        return hitch_mcp_origin_denied! unless allowed
+
+        response.headers["Access-Control-Allow-Origin"] = request.get_header("HTTP_ORIGIN")
+        Internal::CorsPolicy::PREFLIGHT_RESPONSE_HEADERS.each do |header, value|
+          response.headers[header] = value
+        end
+        head :no_content
+      end
+
+      def hitch_mcp_unauthorized!
+        hitch_mcp_explain!("no usable bearer token for this resource")
+        response.headers["WWW-Authenticate"] = Internal::BearerChallenge.challenge
+        response.headers["Access-Control-Expose-Headers"] = "WWW-Authenticate"
+        head :unauthorized
+      end
+
+      def hitch_mcp_insufficient_scope!(required_scopes)
+        response.headers["WWW-Authenticate"] =
+          Internal::BearerChallenge.insufficient_scope(required_scopes)
+        response.headers["Access-Control-Expose-Headers"] = "WWW-Authenticate"
+        head :forbidden
+      end
+
+      # Every refusal above answers with an empty body on purpose. In
+      # development and test the reason goes to the local log instead, so a
+      # 400 is a sentence rather than a silence.
+      def hitch_mcp_explain!(reason)
+        Internal::LocalDiagnosis.report("MCP request refused: #{reason}")
+      end
+
+      def hitch_mcp_append_vary!(value)
+        values = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+        values << value unless values.include?(value)
+        response.headers["Vary"] = values.join(", ")
+      end
+
+      def hitch_mcp_tools(verified_request:, context:, snapshot:)
+        if verified_request.fetch("method") == "tools/call"
+          resolution = Internal::RegistryRuntime.runtime_call(
+            snapshot:,
+            name: verified_request.fetch("params").fetch("name"),
+            context:
+          )
+          if %i[available insufficient_scope].include?(resolution.status)
+            @hitch_mcp_observation&.tool_resolved!(verified_request.fetch("params").fetch("name"))
+          end
+          if resolution.status == :insufficient_scope
+            hitch_mcp_insufficient_scope!(resolution.required_scopes)
+            return [].freeze
+          end
+
+          return resolution.status == :available ? [ resolution.tool ].freeze : [].freeze
+        end
+
+        Internal::RegistryRuntime.runtime_listing(snapshot:, context:)
+      end
+
+      # Counts through the host application's own cache store, exactly as
+      # ActionController::RateLimiting does. A nil count admits, same as
+      # Rails: :null_store returns nil (test, and development without
+      # caching — production refuses those stores at boot), and Redis and
+      # Solid Cache stores return nil during a backend outage rather than
+      # raising. This request is already authenticated, so an outage widens
+      # one token holder's quota, not the front door. Anything else a store
+      # returns fails the comparison above and becomes a 503.
+      def hitch_mcp_admit_authenticated_request(principal:, client_id:)
+        configuration = Hitch.configuration.mcp
+        configuration.rate_limit_store.increment(
+          RateLimitKey.call(principal:, client_id:),
+          expires_in: configuration.request_limit.fetch(:within)
+        )
+      end
+
+      def hitch_mcp_request_observed!
+        @hitch_mcp_observation&.finish!(response:)
+      end
+    end
+  end
+end