hitch-rails 0.2.0

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  # Rails records `request.filtered_parameters` before controller callbacks.
+  # For OAuth form endpoints that would let Rack parse an unbounded credential
+  # body before a conventional body-limit callback could run. This concern sits
+  # earlier in the `process_action` chain, caps the raw stream, and installs a
+  # deliberately minimal body-parameter cache for Rails instrumentation.
+  #
+  # Endpoint actions still parse the bounded raw form through
+  # OauthRequestParameters, preserving duplicate and structured-key evidence.
+  # The browser-backed consent POST retains only its CSRF token in Rails params;
+  # public token and revocation endpoints expose no body fields to instrumentation.
+  module OauthFormAdmission
+    extend ActiveSupport::Concern
+
+    include Hitch::RequestAdmission
+
+    private
+
+    def process_action(action_name, ...)
+      if action_name.to_s == "create" && request.post?
+        unless admit_oauth_form_request!
+          finalize_hitch_admission_rejection!
+          return
+        end
+      end
+
+      super
+    end
+
+    def admit_oauth_form_request!
+      prepare_oauth_form_response!
+      request.request_parameters = {}
+      unless hitch_request_origin_allowed?
+        require_allowed_hitch_host!
+        return false
+      end
+
+      raw_body = bounded_oauth_form_body
+      return false if performed?
+
+      request.request_parameters = hitch_instrumentation_form_parameters(raw_body)
+      true
+    end
+
+    def bounded_oauth_form_body
+      bytes = hitch_read_bounded_request_body(self.class::MAX_REQUEST_BODY_BYTES)
+      return bytes if bytes
+
+      reject_oversized_oauth_form_body!
+      ""
+    end
+
+    def hitch_instrumentation_form_parameters(raw_body)
+      return {} unless preserve_oauth_authenticity_token?
+
+      values = raw_body.split("&").filter_map do |pair|
+        encoded_key, encoded_value = pair.split("=", 2)
+        next unless decode_form_component(encoded_key) == "authenticity_token"
+
+        decode_form_component(encoded_value.to_s)
+      end
+
+      values.one? ? { "authenticity_token" => values.first } : {}
+    end
+
+    def decode_form_component(value)
+      URI.decode_www_form_component(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def preserve_oauth_authenticity_token?
+      false
+    end
+
+    def prepare_oauth_form_response!
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hitch
+  module OauthParameterValidation
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from Hitch::OauthRequestParameters::Invalid, with: :render_oauth_parameter_error
+    end
+
+    private
+
+    def oauth_parameters(*allowed, form_only: false)
+      Hitch::OauthRequestParameters.new(request, allowed: allowed, form_only: form_only).to_h
+    end
+
+    # Render an OAuth-formatted JSON error.
+    def oauth_error(code, description, status = :bad_request)
+      render json: { error: code, error_description: description }, status: status
+    end
+
+    def render_oauth_parameter_error(error)
+      oauth_error("invalid_request", error.message)
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hitch
+  # Dynamic Client Registration is an unauthenticated write endpoint. Rails'
+  # controller instrumentation reads `request.filtered_parameters` before it
+  # runs before_action callbacks, which means a callback cannot honestly cap,
+  # rate-limit, or validate a JSON body before Rails parses it.
+  #
+  # This concern participates in ActionController's `process_action` chain one
+  # level earlier. It admits the request, parses one bounded JSON document with
+  # duplicate keys forbidden, and installs that verified Hash as Rails' cached
+  # request parameters. Instrumentation and the action then reuse the same
+  # object instead of parsing attacker-controlled input a second time.
+  module RegistrationAdmission
+    extend ActiveSupport::Concern
+
+    include Hitch::RequestAdmission
+
+    ADMITTED_HEADER = "hitch.registration_admitted"
+
+    private
+
+    def process_action(action_name, ...)
+      return super unless action_name.to_s == "create"
+      unless admit_registration_request!
+        finalize_hitch_admission_rejection!
+        return
+      end
+
+      super
+    end
+
+    def admit_registration_request!
+      response.headers["Cache-Control"] = "no-store"
+      response.headers["Pragma"] = "no-cache"
+
+      # Error rendering and host callbacks can consult `params`. Install an
+      # empty body-parameter cache before either can accidentally invoke Rails'
+      # JSON parser; a successful strict parse replaces it below.
+      request.request_parameters = {}
+
+      return false unless admit_registration_host!
+      return false unless admit_registration_mode!
+      return false unless admit_registration_media_type!
+      return false unless admit_registration_rate!
+
+      raw_body = bounded_registration_body
+      return false if performed?
+
+      metadata = JSON.parse(raw_body, allow_duplicate_key: false)
+      unless metadata.is_a?(Hash)
+        oauth_error("invalid_client_metadata", "registration metadata must be a JSON object")
+        return false
+      end
+
+      request.request_parameters = metadata
+      request.set_header(ADMITTED_HEADER, true)
+      true
+    rescue JSON::ParserError
+      oauth_error("invalid_client_metadata", "request body must be valid JSON")
+      false
+    end
+
+    def admit_registration_host!
+      return true if hitch_request_origin_allowed?
+
+      require_allowed_hitch_host!
+      false
+    end
+
+    def admit_registration_mode!
+      return true if Hitch.configuration.dynamic_client_registration_enabled
+
+      head :not_found
+      false
+    end
+
+    def admit_registration_media_type!
+      return true if request.media_type == "application/json"
+
+      oauth_error(
+        "invalid_client_metadata",
+        "Content-Type must be application/json",
+        :unsupported_media_type
+      )
+      false
+    end
+
+    def admit_registration_rate!
+      Hitch::DynamicRegistrationRateLimit.check!(remote_ip: request.remote_ip)
+      true
+    rescue Hitch::DynamicRegistrationRateLimit::Exceeded => error
+      response.headers["Retry-After"] = error.retry_after.to_s
+      oauth_error("temporarily_unavailable", "Registration rate limit exceeded", :too_many_requests)
+      false
+    rescue Hitch::DynamicRegistrationRateLimit::Unavailable
+      oauth_error("temporarily_unavailable", "Registration is temporarily unavailable", :service_unavailable)
+      false
+    end
+
+    def bounded_registration_body
+      bytes = hitch_read_bounded_request_body(self.class::MAX_REQUEST_BODY_BYTES)
+      return bytes if bytes
+
+      oauth_error(
+        "invalid_client_metadata",
+        "registration request body exceeds #{self.class::MAX_REQUEST_BODY_BYTES} bytes",
+        :content_too_large
+      )
+      ""
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Shared mechanics for controller admission that must run before Rails
+  # instrumentation parses request parameters. Policy remains in the endpoint-
+  # specific concerns.
+  module RequestAdmission
+    extend ActiveSupport::Concern
+
+    # Default cap on request bodies for the OAuth endpoints. Read via
+    # `self.class::MAX_REQUEST_BODY_BYTES`, so a controller may override
+    # it with its own constant.
+    MAX_REQUEST_BODY_BYTES = 16_384
+
+    private
+
+    def hitch_read_bounded_request_body(max_bytes)
+      stream = request.body
+      stream.rewind if stream.respond_to?(:rewind)
+      limit = max_bytes + 1
+      bytes = +"".b
+
+      # Rack inputs may return a short chunk without being at EOF. Continue
+      # until EOF or the cap sentinel instead of treating one short read as the
+      # complete trusted body.
+      while bytes.bytesize < limit
+        chunk = stream.read(limit - bytes.bytesize)
+        break if chunk.nil? || chunk.empty?
+
+        bytes << chunk.to_s.b
+      end
+      return if bytes.bytesize > max_bytes
+
+      # Rack does not require rack.input to implement rewind. Rails replays a
+      # cached RAW_POST_DATA value through StringIO, so accepted bytes remain
+      # available to request.raw_post and any later consumer without touching
+      # the original stream a second time.
+      request.set_header("RAW_POST_DATA", bytes)
+      bytes
+    end
+
+    def finalize_hitch_admission_rejection!
+      set_cors_headers if respond_to?(:set_cors_headers, true)
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Shared OAuth URI validation rules used by both the authorization
+  # endpoint (per-request `redirect_uri`) and the DCR endpoint
+  # (`redirect_uris` array at registration time).
+  #
+  # Without DCR-time validation, an attacker could register a client
+  # with `javascript:alert(1)` or `http://attacker.test/cb` and then
+  # try to use it at authorize — RFC 7591 §2 makes URI policy the
+  # authorization server's responsibility.
+  module UriValidation
+    extend ActiveSupport::Concern
+
+    private
+
+    # Authorization redirect URI: https everywhere except loopback
+    # http (which RFC 8252 permits for native apps).
+    def valid_redirect_uri?(uri)
+      parsed = URI.parse(uri)
+      return false if parsed.hostname.blank?
+      return false unless parsed.userinfo.nil? && !userinfo_component_present?(uri)
+      # RFC 6749 §3.1.2: the redirection endpoint URI MUST NOT include a
+      # fragment component. Enforced because redirect_uri_matches? does
+      # not compare fragments either, so one would otherwise ride through
+      # unvalidated — and a client that scans location.hash for response
+      # parameters (a real pattern in libraries supporting both query and
+      # fragment response modes) would read whatever was smuggled there.
+      return false unless parsed.fragment.nil?
+
+      case parsed.scheme
+      when "https" then true
+      when "http"  then loopback_host?(parsed.hostname)
+      else false
+      end
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def loopback_host?(host)
+      Hitch::ResourceUri::LOOPBACK_HOSTS.include?(host)
+    end
+
+    def userinfo_component_present?(value)
+      Hitch::ResourceUri.userinfo_component_present?(value)
+    end
+
+    # Exact comparison, with exactly one exception.
+    #
+    # RFC 9700 §4.1.3 and MCP 2026-07-28 ("Authorization servers MUST
+    # validate exact redirect URIs against pre-registered values") both
+    # require the inbound redirect_uri to match a registered one exactly.
+    # RFC 8252 §7.3 grants a single carve-out: a native app using a
+    # loopback redirect MAY pick an ephemeral port per session, so the
+    # PORT — and only the port — may differ there. Claude Code relies on
+    # this.
+    #
+    # The query string is compared. Skipping it meant a caller could
+    # append parameters a client's callback reads (`next`, `returnTo`, a
+    # tenant selector) to a registration that never contained them, and
+    # — before those parameters were stripped downstream — shadow the
+    # OAuth response parameters outright. Stripping remains in place as
+    # defense in depth; this is the control.
+    #
+    # Fragments and userinfo are refused on both sides. Neither is
+    # comparable in any meaningful way, RFC 6749 §3.1.2 forbids a
+    # fragment on a redirection endpoint, and a userinfo component would
+    # let `https://evil%40x:pw@claude.ai/cb` match a registration of
+    # `https://claude.ai/cb`.
+    def redirect_uri_matches?(registered, inbound)
+      reg = URI.parse(registered)
+      inb = URI.parse(inbound)
+
+      return false unless reg.fragment.nil? && inb.fragment.nil?
+      return false unless reg.userinfo.nil? && inb.userinfo.nil?
+      return false if userinfo_component_present?(registered) || userinfo_component_present?(inbound)
+      return false unless reg.scheme == inb.scheme
+      return false unless reg.hostname == inb.hostname
+      return false unless reg.path == inb.path
+      return false unless reg.query == inb.query
+
+      return true if reg.scheme == "http" && loopback_host?(reg.hostname)
+
+      reg.port == inb.port
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # RFC 8707 audience binding, shared by the authorize and token
+    # endpoints: the request's `resource` must canonicalize to exactly
+    # the resource this server is configured to protect. Returns the
+    # canonical resource string, or nil after rendering the OAuth error.
+    def require_canonical_resource(value)
+      if value.blank?
+        oauth_error("invalid_target", "resource is required")
+        return nil
+      end
+
+      allow_loopback = Rails.env.local?
+      requested = Hitch::ResourceUri.canonicalize!(value, allow_loopback_http: allow_loopback)
+      configured = Hitch::ResourceUri.canonicalize!(
+        Hitch.configuration.resource_uri,
+        allow_loopback_http: allow_loopback
+      )
+      unless requested == configured
+        oauth_error("invalid_target", "resource does not identify this MCP server")
+        return nil
+      end
+
+      requested
+    rescue Hitch::ResourceUri::Invalid => error
+      oauth_error("invalid_target", error.message)
+      nil
+    end
+  end
+end

data/app/controllers/hitch/application_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Hitch
+  # All gem controllers inherit from the host's ApplicationController so
+  # the host's authentication concern, layout, helpers, and middleware
+  # apply automatically. The gem only adds OAuth-specific behavior on
+  # top.
+  class ApplicationController < ::ApplicationController
+    include Hitch::HostValidation
+    include Hitch::IssuerUrl
+    include Hitch::OauthParameterValidation
+
+    # Opt out of the host's blanket authentication-enforcement callback.
+    # Rails 8's built-in `bin/rails g authentication` adds a global
+    # `before_action :require_authentication` to the host's
+    # ApplicationController, which this consent controller inherits. That
+    # callback redirects unauthenticated visitors to the host's sign-in
+    # via `new_session_path` — but evaluated inside the isolated engine's
+    # routing context that helper doesn't resolve, raising
+    # UrlGenerationError before the gem's own logic runs. The consent
+    # screen does its OWN principal resolution (current_principal +
+    # require_principal!, which honors config.login_path), so it must not
+    # be pre-empted. `raise: false` makes this a no-op for hosts that
+    # don't define the callback (Devise, plain apps, etc.).
+    skip_before_action :require_authentication, raise: false
+
+    # Resolve the current authenticated principal.
+    #
+    # 1. Call the host-configured method (default :current_user) if the
+    #    host defines it — covers Devise, has_secure_password apps, and
+    #    anything that exposes a current_user-style helper.
+    # 2. Otherwise fall back to Rails 8's built-in authentication
+    #    generator, which exposes the signed-in user as Current.user
+    #    (delegated from Current.session) and defines NO current_user
+    #    controller method. Without this fallback, a stock Rails 8 auth
+    #    app would treat every visitor as unauthenticated and the consent
+    #    screen would never render.
+    #
+    # Returns nil when neither resolves — the controllers handle nil as
+    # "unauthenticated".
+    def current_principal
+      method_name = Hitch.configuration.principal_method
+      return send(method_name) if respond_to?(method_name, true)
+
+      # Rails 8 built-in auth exposes the signed-in user as Current.user,
+      # populated by the host's `resume_session` — which normally runs
+      # inside the `require_authentication` before_action that we skip (it
+      # redirects via a host route that doesn't resolve in the engine).
+      # So resume the session ourselves before reading Current.user;
+      # without this, a signed-in user looks unauthenticated here and the
+      # consent screen loops back to login. `resume_session` is idempotent
+      # (Current.session ||= …); guarded for hosts that don't define it.
+      resume_session if respond_to?(:resume_session, true)
+      return Current.user if defined?(Current) && Current.respond_to?(:user)
+
+      nil
+    end
+  end
+end

data/app/controllers/hitch/authorizations_controller.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Hitch
+  # GET /oauth/authorize  — render consent screen
+  # POST /oauth/authorize — issue authorization code
+  #
+  # Session-authenticated. Inherits the host's auth concern through
+  # Hitch::ApplicationController. If current_principal is nil, the
+  # controller redirects to Hitch.configuration.login_path (or
+  # returns 401 if unset).
+  #
+  # RFC 8707 audience binding: the `resource` param sent by the client
+  # is persisted on the access token at issue time and validated at
+  # token-use time, satisfying the MCP authorization spec's audience MUST.
+  #
+  # The flow's HTTP-free reasoning — parameter validation, client and
+  # redirect resolution, scope clamping, redirect construction — lives in
+  # Hitch::AuthorizationRequest; this controller renders its decisions.
+  class AuthorizationsController < Hitch::ApplicationController
+    include Hitch::OauthFormAdmission
+
+    AUTHORIZATION_PARAMETER_NAMES = %i[
+      response_type
+      client_id
+      redirect_uri
+      scope
+      state
+      code_challenge
+      code_challenge_method
+      resource
+    ].freeze
+
+    # The consent POST is a state-changing, session-authenticated
+    # action, so it MUST be CSRF-protected. Declared here rather than
+    # relying on the host's ApplicationController to have forgery
+    # protection enabled — an API-only host, or one that disables it
+    # app-wide, would otherwise leave Approve forgeable (an attacker
+    # auto-approving an authorization in a logged-in victim's session).
+    # The rendered consent form (form_with) carries the token, so
+    # legitimate submits are unaffected. Guarded: an
+    # ActionController::API-derived host base doesn't define the macro,
+    # and such a host can't serve the HTML consent screen anyway.
+    protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
+
+    def new
+      return require_principal! unless current_principal
+
+      authorization = authorization_request(*AUTHORIZATION_PARAMETER_NAMES)
+      return authorization_error(authorization) unless authorization.valid?
+
+      @oauth_params = authorization.params
+      @redirect_host = authorization.redirect_host
+      @client_name = authorization.display_client_name
+      @brand_name = Hitch.configuration.brand_name
+      @resource = authorization.resource
+      @localhost_only_client = authorization.localhost_only_client?
+      # Show the user exactly what they're approving (clamped to the
+      # server allowlist — never echo an unsupported requested scope).
+      @scopes = authorization.granted_scopes
+    end
+
+    def create
+      return require_principal! unless current_principal
+
+      authorization = authorization_request(*AUTHORIZATION_PARAMETER_NAMES, :decision)
+      return authorization_error(authorization) unless authorization.valid?
+
+      # RFC 6749 §4.1.2.1: the user declining is reported to the validated
+      # redirect_uri as access_denied — with iss, like every redirect.
+      if authorization.deny?
+        return redirect_to_client(
+          authorization.redirect_uri_for(error: "access_denied", state: authorization.state)
+        )
+      end
+
+      token = Hitch::AccessToken.create_authorization!(
+        principal: current_principal,
+        client_id: authorization.client_id,
+        client_name: authorization.audit_client_name,
+        redirect_uri: authorization.redirect_uri,
+        code_challenge: authorization.code_challenge,
+        code_challenge_method: authorization.code_challenge_method,
+        resource_uri: authorization.resource,
+        scopes: authorization.granted_scopes
+      )
+
+      redirect_to_client(
+        authorization.redirect_uri_for(code: token.raw_authorization_code, state: authorization.state)
+      )
+    end
+
+    private
+
+    def authorization_request(*names)
+      Hitch::AuthorizationRequest.new(
+        oauth_parameters(*names),
+        principal: current_principal
+      )
+    end
+
+    def authorization_error(authorization)
+      error = authorization.error
+      oauth_error(error.code, error.description, error.status)
+    end
+
+    def reject_oversized_oauth_form_body!
+      oauth_error(
+        "invalid_request",
+        "authorization request body exceeds #{MAX_REQUEST_BODY_BYTES} bytes",
+        :content_too_large
+      )
+    end
+
+    def preserve_oauth_authenticity_token?
+      true
+    end
+
+    # Action Controller's ordinary redirect helper emits the complete Location
+    # through `redirect_to.action_controller`; Rails' log subscriber then
+    # writes the one-time authorization code in plaintext. The destination has
+    # already passed exact registered-URI validation, so construct the 302
+    # directly and keep the credential out of redirect instrumentation.
+    def redirect_to_client(location)
+      response.headers["Cache-Control"] = "no-store"
+      response.headers["Pragma"] = "no-cache"
+      response.headers["Location"] = location
+      head :found
+    end
+
+    def require_principal!
+      # Remember where the user was headed so the host's auth flow returns
+      # them to the consent screen after login. Rails 8's built-in
+      # authentication reads session[:return_to_after_authenticating] in
+      # after_authentication_url; normally its own require_authentication
+      # callback sets this, but the consent controller skips that callback
+      # (see ApplicationController) and redirects to login_path itself, so
+      # we set the return location here. Harmless for hosts that never read
+      # the key. Only meaningful on the GET consent render — a POST without
+      # a session isn't a real flow.
+      session[:return_to_after_authenticating] = request.url if request.get?
+
+      path = Hitch.configuration.login_path
+      target = path.respond_to?(:call) ? path.call(request) : path
+
+      if target.present?
+        redirect_to target, allow_other_host: true
+      else
+        render plain: "Authentication required", status: :unauthorized
+      end
+    end
+  end
+end