hitch-rails 0.2.0

data/lib/hitch/rack_form_guard.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "uri"
+
+module Hitch
+  # Rack::MethodOverride parses every form POST before Rails dispatches a
+  # controller. Hitch's OAuth endpoints and final MCP endpoint own stricter raw
+  # body parsers, so pre-populate Rack's form cache only when Rails resolves the
+  # request to one of those actions. Resolving ownership matters: Rails accepts
+  # format/trailing-slash variants, host routes may shadow the engine, and the
+  # MCP controller/route remain host-owned.
+  class RackFormGuard
+    ENDPOINTS = {
+      "hitch/authorizations" => "create",
+      "hitch/registrations" => "create",
+      "hitch/revocations" => "create",
+      "hitch/tokens" => "create"
+    }.freeze
+    OAUTH_CANDIDATE_PATH = %r{/(?:oauth)/(?:authorize|register|revoke|token)(?:\.[^/]*)?/?\z}
+
+    def initialize(app, routes: -> { Rails.application.routes })
+      @app = app
+      @routes = routes
+    end
+
+    def call(environment)
+      route_type = hitch_strict_body_route(environment)
+      if route_type
+        environment[Rack::RACK_REQUEST_FORM_HASH] = {}
+        environment[Rack::RACK_REQUEST_FORM_PAIRS] = []
+        # The MCP route is permanently POST/OPTIONS. A generic Rack method
+        # override must neither parse its body nor turn authenticated POST
+        # traffic into an unauthenticated OPTIONS request.
+        environment.delete("HTTP_X_HTTP_METHOD_OVERRIDE") if route_type == :mcp
+      end
+
+      @app.call(environment)
+    end
+
+    private
+
+    def hitch_strict_body_route(environment)
+      return false unless environment[Rack::REQUEST_METHOD] == "POST"
+
+      # Match RouteSet#call exactly before narrowing the ownership probe. Rails
+      # collapses repeated slashes but deliberately does not resolve dot
+      # segments; applying the candidate filter to raw PATH_INFO would miss
+      # routes Rails later dispatches.
+      normalized_path = ActionDispatch::Journey::Router::Utils.normalize_path(environment[Rack::PATH_INFO])
+      return false unless hitch_candidate_path?(normalized_path)
+
+      # Route recognition must not share the credential-bearing input or
+      # path-parameter cache with the request Rails will actually dispatch.
+      # Host route constraints still receive the real method/host/headers, but
+      # cannot become an earlier body reader through this ownership probe.
+      probe_environment = environment.dup
+      probe_environment.delete("action_dispatch.request.path_parameters")
+      probe_environment["rack.input"] = StringIO.new
+      probe_environment[Rack::RACK_REQUEST_FORM_HASH] = {}
+      probe_environment[Rack::RACK_REQUEST_FORM_PAIRS] = []
+      probe_environment["CONTENT_LENGTH"] = "0"
+      probe_environment[Rack::PATH_INFO] = normalized_path
+
+      request = ActionDispatch::Request.new(probe_environment)
+      parameters = route_set.recognize_path_with_request(
+        request,
+        normalized_path,
+        {},
+        raise_on_missing: false
+      )
+      return false unless parameters
+      return :oauth if hitch_oauth_endpoint?(parameters)
+      return :mcp if hitch_mcp_endpoint?(parameters)
+
+      false
+    rescue ActionController::RoutingError
+      false
+    end
+
+    def route_set
+      @routes.respond_to?(:call) ? @routes.call : @routes
+    end
+
+    def hitch_oauth_endpoint?(parameters)
+      ENDPOINTS[parameters[:controller]] == parameters[:action]
+    end
+
+    def hitch_mcp_endpoint?(parameters)
+      return false unless parameters[:action] == "handle"
+
+      controller_name = parameters[:controller].to_s
+      return false if controller_name.empty?
+
+      controller = "#{controller_name.camelize}Controller".safe_constantize
+      controller && controller.ancestors.include?(Hitch::MCP::Endpoint)
+    end
+
+    def hitch_candidate_path?(path)
+      return true if OAUTH_CANDIDATE_PATH.match?(path)
+
+      resource_path = URI.parse(Hitch.configuration.resource_uri.to_s).path
+      resource_path = "/" if resource_path.empty?
+      %r{\A#{Regexp.escape(resource_path)}(?:\.[^/]*)?/?\z}.match?(path)
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end

data/lib/hitch/rate_limit_store.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Both Hitch rate limits — unauthenticated client registration and
+  # authenticated MCP requests — count through the host application's own
+  # ActiveSupport::Cache store, the way ActionController::RateLimiting does.
+  # Neither adds a service to the deployment, and neither asks the host to
+  # implement an interface.
+  module RateLimitStore
+    class << self
+      def resolve(configured)
+        configured || ActionController::Base.cache_store
+      end
+
+      def validate!(store, setting:)
+        return store if store.nil? || store.respond_to?(:increment)
+
+        raise ArgumentError,
+          "#{setting} must be an ActiveSupport::Cache store responding to increment"
+      end
+
+      # Production boot check, shared by both limiters: the resolved store
+      # must be able to count one caller's requests across processes. Unlike
+      # validate!, nil is refused here — there is no later to resolve at.
+      def assert_shared!(store, setting:)
+        unless store.respond_to?(:increment)
+          raise ArgumentError,
+            "#{setting} must be an ActiveSupport::Cache store responding to increment"
+        end
+        return true unless unshared?(store)
+
+        raise ArgumentError,
+          "#{setting} resolved to #{store.class.name}, which cannot count one caller's " \
+            "requests across the processes serving them. Configure a shared " \
+            "config.cache_store (Solid Cache, Redis, Memcached) or set #{setting} explicitly."
+      end
+
+      # MemoryStore is per process, NullStore retains nothing, and FileStore
+      # reads and writes without a lock.
+      def unshared?(store)
+        store.is_a?(ActiveSupport::Cache::MemoryStore) ||
+          store.is_a?(ActiveSupport::Cache::NullStore) ||
+          store.is_a?(ActiveSupport::Cache::FileStore)
+      end
+    end
+  end
+end

data/lib/hitch/resource_uri.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  class ResourceUri
+    class Invalid < ArgumentError; end
+
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+    def self.canonicalize!(value, allow_loopback_http: false)
+      uri = URI.parse(value.to_s)
+      scheme = uri.scheme.to_s.downcase
+      host = uri.hostname.to_s.downcase
+
+      raise Invalid, "resource must be an absolute HTTP URI" unless uri.absolute? && host.present?
+      unless uri.userinfo.nil? && !userinfo_component_present?(value)
+        raise Invalid, "resource must not include userinfo"
+      end
+      raise Invalid, "resource must not include a fragment" unless uri.fragment.nil?
+      unless scheme == "https" || (scheme == "http" && allow_loopback_http && LOOPBACK_HOSTS.include?(host))
+        raise Invalid, "resource must use HTTPS"
+      end
+
+      canonical = uri.dup
+      canonical.scheme = scheme
+      canonical.hostname = host
+      canonical.port = nil if canonical.port == canonical.default_port
+      canonical.to_s
+    rescue URI::InvalidURIError
+      raise Invalid, "resource must be an absolute HTTP URI"
+    end
+
+    # The `host[:port]` authority, with the port omitted when it is the
+    # scheme's default. URI already brackets IPv6 literals in #host and
+    # already knows each scheme's default port, so neither rule is restated
+    # here or at any call site.
+    def self.authority(uri)
+      uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+    end
+
+    # The origin (RFC 6454): scheme and authority, no path, query, or
+    # fragment. The authorization server's issuer identifier is the origin of
+    # the canonical resource_uri (RFC 8414 §2), and it MUST be byte-identical
+    # in the discovery document, the `iss` authorization response parameter
+    # (RFC 9207), and every bearer challenge. One derivation is what makes
+    # that true by construction rather than by convention.
+    def self.origin(uri)
+      "#{uri.scheme}://#{authority(uri)}"
+    end
+
+    # The path-aware protected-resource metadata URL (RFC 9728 §3.1): the
+    # well-known segment sits between the origin and the resource's own path.
+    # Derives its own origin so a caller cannot pair this path with a
+    # different issuer.
+    def self.protected_resource_metadata_url(uri)
+      path = uri.path.to_s
+      suffix = path.empty? || path == "/" ? "" : path
+      query = uri.query ? "?#{uri.query}" : ""
+
+      "#{origin(uri)}/.well-known/oauth-protected-resource#{suffix}#{query}"
+    end
+
+    # URI.parse can miss a userinfo component that a raw scan of the
+    # authority still finds; callers use both checks together.
+    def self.userinfo_component_present?(value)
+      authority = value.to_s.match(/\A[a-z][a-z0-9+.-]*:\/\/([^\/?#]*)/i)&.captures&.first
+      authority&.include?("@") || false
+    end
+  end
+end

data/lib/hitch/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hitch
+  VERSION = "0.2.0"
+end

data/lib/hitch-rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Shim so Bundler.require finds the gem under its dasherized name.
+# All real code lives in lib/hitch.rb (underscore matches the
+# module namespace Hitch).
+require "hitch"

data/lib/hitch.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "hitch/version"
+require "hitch/rack_form_guard"
+require "hitch/rate_limit_store"
+require "hitch/engine"
+require "hitch/resource_uri"
+require "hitch/pkce"
+require "hitch/mcp/protocol"
+require "hitch/mcp/configuration"
+require "hitch/configuration"
+require "hitch/dynamic_registration_rate_limit"
+
+# hitch-rails turns a Rails app into an authorization server implemented
+# against the MCP 2026-07-28 authorization profile — OAuth 2.1 + PKCE (S256),
+# Resource Indicators with audience binding (RFC 8707), discovery metadata
+# (RFC 8414 + RFC 9728), token revocation (RFC 7009), and CORS for
+# browser-based MCP clients — plus an authenticated host-mounted MCP endpoint
+# with a deny-default tool Registry behind a private Ruby SDK boundary, rate
+# limiting counted through the host application's own cache store, sanitized
+# observation events, and a read-only operator doctor.
+#
+# Spec reference: https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+#
+# Usage:
+#   # config/initializers/hitch.rb
+#   Hitch.configure do |config|
+#     config.resource_uri = "https://example.com/mcp"  # for RFC 8707
+#     config.allowed_hosts = []
+#     config.allowed_origins = []
+#   end
+module Hitch
+  class << self
+    # @yield [Configuration] the gem's configuration
+    # @return [Configuration] the (potentially modified) configuration
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset configuration (useful in tests).
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

data/lib/tasks/hitch.rake

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "hitch/doctor"
+
+module Hitch
+  # Argument parsing for hitch:tokens:issue. Kept out of the task body so a
+  # bad PRINCIPAL aborts with a sentence instead of a NameError.
+  module TokenIssueTask
+    module_function
+
+    # rpartition, not split: a namespaced principal (Accounts::User:5) has
+    # colons in the model half, and only the last one separates the id.
+    def principal!(value)
+      model_name, _, id = value.to_s.rpartition(":")
+      abort "PRINCIPAL is required, as Model:id (for example User:1)" if model_name.blank? || id.blank?
+
+      model = model_name.safe_constantize
+      unless model.is_a?(Class) && model < ActiveRecord::Base
+        abort "PRINCIPAL model #{model_name} is not an Active Record model"
+      end
+      abort "PRINCIPAL model #{model_name} is abstract; name the model that stores the record" if
+        model.abstract_class?
+
+      # Numeric keys silently absorb junk: Rails casts "12 34" to 12, so a
+      # typo would issue a token for somebody else. UUID, ULID and string
+      # keys are matched exactly by the adapter, or raise, so they are left
+      # alone — including the upcased and undashed UUID forms that resolve
+      # correctly.
+      numeric_key = %i[integer decimal float].include?(
+        model.type_for_attribute(model.primary_key).type
+      )
+      if numeric_key && !id.match?(/\A\d+\z/)
+        abort "PRINCIPAL id #{id.inspect} is not a whole number"
+      end
+
+      model.find(id)
+    rescue ActiveRecord::RecordNotFound
+      abort "No #{model_name} with id #{id}"
+    end
+
+    # Long enough that a cron agent is not reissued monthly, short enough
+    # that an unnoticed leak expires.
+    def days!(value)
+      return 90 if value.blank?
+
+      days = Integer(value, 10, exception: false)
+      abort "EXPIRES_IN_DAYS must be a positive whole number of days" unless days&.positive?
+      # The ceiling is the model's, so there is one answer to how long a
+      # token may live rather than two that can drift.
+      max = Hitch::AccessToken::MAX_LIFETIME_SECONDS / 86_400
+      abort "EXPIRES_IN_DAYS must not exceed #{max}" if days > max
+
+      days
+    end
+  end
+
+  module ClientCredentialTask
+    module_function
+
+    # The block returns the exact bytes to disclose. A client registration
+    # hands over two values and labels them; a token is one value, and what
+    # lands in the file has to be usable as `Authorization: Bearer $(cat …)`
+    # without anyone having to know a file format.
+    def disclose(stdin: $stdin, tty_path: "/dev/tty")
+      with_output(stdin: stdin, tty_path: tty_path) do |output|
+        Hitch::ApplicationRecord.transaction do
+          disclosed = yield
+          # A secret is what gets written; anything else is a caller mistake
+          # worth failing on rather than serialising.
+          raise TypeError, "disclose must be given the exact bytes to write" unless
+            disclosed.is_a?(String)
+
+          output.write(disclosed.end_with?("\n") ? disclosed : "#{disclosed}\n")
+          output.flush
+        end
+      end
+    end
+
+    def with_output(stdin:, tty_path:)
+      output_path = ENV["OUTPUT_FILE"].presence
+      if output_path
+        with_exclusive_file(output_path) { |output| yield output }
+      elsif stdin.tty?
+        File.open(tty_path, File::WRONLY) { |output| yield output }
+      else
+        abort "Set OUTPUT_FILE when standard input is not an interactive terminal"
+      end
+    end
+
+    def with_exclusive_file(path)
+      output = File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600)
+      begin
+        output.chmod(0o600)
+        yield output
+      rescue Exception # rubocop:disable Lint/RescueException -- remove a partially written credential file on every task abort
+        output.close
+        File.unlink(path) if File.exist?(path)
+        raise
+      ensure
+        output.close unless output.closed?
+      end
+    rescue Errno::EEXIST
+      abort "Refusing to overwrite existing OUTPUT_FILE"
+    end
+  end
+end
+
+namespace :hitch do
+  desc "Diagnose Hitch configuration, routes, schema, registry, and admission store"
+  task doctor: :environment do
+    format = ENV.fetch("HITCH_DOCTOR_FORMAT", "human")
+    report = Hitch::Doctor.call
+    puts Hitch::Doctor.render(report, format:)
+    exit(1) if report.failure?
+  rescue ArgumentError => error
+    abort error.message
+  end
+
+  namespace :clients do
+    desc "Create a confidential OAuth client and disclose its one-time secret safely"
+    task create_confidential: :environment do
+      client_id = ENV["CLIENT_ID"].presence || abort("CLIENT_ID is required")
+      redirect_uri = ENV["REDIRECT_URI"].presence || abort("REDIRECT_URI is required")
+
+      Hitch::ClientCredentialTask.disclose do
+        credentials = Hitch::Client.register_confidential!(
+          client_id: client_id,
+          client_name: ENV["NAME"],
+          redirect_uris: [ redirect_uri ]
+        )
+        "client_id=#{credentials.client.client_id}\nclient_secret=#{credentials.client_secret}\n"
+      end
+    end
+
+    desc "Rotate a confidential OAuth client's secret and disclose it safely"
+    task rotate_secret: :environment do
+      client_id = ENV["CLIENT_ID"].presence || abort("CLIENT_ID is required")
+
+      Hitch::ClientCredentialTask.disclose do
+        client = Hitch::Client.find_by(client_id: client_id)
+        abort "Confidential client not found" unless client&.confidential_client?
+
+        credentials = client.rotate_secret!
+        "client_id=#{credentials.client.client_id}\nclient_secret=#{credentials.client_secret}\n"
+      end
+    end
+  end
+
+  namespace :tokens do
+    desc "Issue a long-lived access token for a headless agent " \
+         "(usage: bin/rails hitch:tokens:issue PRINCIPAL=User:1)"
+    task issue: :environment do
+      principal = Hitch::TokenIssueTask.principal!(ENV["PRINCIPAL"])
+      scopes = ENV["SCOPES"].to_s.split
+      days = Hitch::TokenIssueTask.days!(ENV["EXPIRES_IN_DAYS"])
+
+      client_id = ENV["CLIENT_ID"].presence || "hitch-cli"
+      Hitch::ClientCredentialTask.disclose do
+        Hitch::AccessToken.issue!(
+          principal: principal,
+          client_id: client_id,
+          client_name: ENV["NAME"],
+          scopes: scopes,
+          expires_in: days * 86_400
+        )
+      end
+
+      # The secret went to the file or the terminal; this goes to stderr, so a
+      # silent success is not mistaken for a no-op. It never names where the
+      # token went, because on a terminal there is no file.
+      warn "Issued an access token for #{principal.class.name}:#{principal.id} " \
+        "(client_id #{client_id}, #{days} days)."
+    end
+  end
+
+  namespace :cimd do
+    desc "Fetch a Client ID Metadata Document to verify this host's egress " \
+         "(usage: bin/rails 'hitch:cimd:check[https://client.example/client.json]')"
+    task :check, [ :client_id ] => :environment do |_task, args|
+      client_id = args[:client_id]
+      abort "Usage: bin/rails 'hitch:cimd:check[https://client.example/client.json]'" if client_id.blank?
+
+      # Reports; never changes what discovery advertises. Whether this
+      # host can reach one document today is a different question from
+      # whether it supports CIMD, and only the second belongs in the
+      # discovery document.
+      result = Hitch::ClientIdMetadata.diagnose(client_id)
+
+      puts "client_id: #{client_id}"
+      puts "outcome:   #{result.outcome}"
+      puts "detail:    #{result.detail}"
+      puts
+      puts(result.ok? ? "Egress to this document works." : "This host could not resolve that document.")
+      exit(1) unless result.ok?
+    end
+  end
+end