hitch-rails 0.2.0

data/app/models/hitch/mcp/rate_limit_key.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    class RateLimitKey
+      SALT = "hitch/mcp/rate-limit/v1"
+      KEY_PREFIX = "hitch:mcp:rate-limit:v1:"
+
+      class << self
+        def call(principal:, client_id:, key_generator: Rails.application.key_generator)
+          record_class = principal.class.respond_to?(:base_class) ? principal.class.base_class : principal.class
+          invalid_message = "MCP request rate identity is invalid"
+          digest = Internal::HmacIdentity.digest(
+            salt: SALT,
+            components: [
+              Internal::HmacIdentity.component(record_class.name, invalid_message:),
+              Internal::HmacIdentity.component(principal.id.to_s, invalid_message:),
+              Internal::HmacIdentity.component(client_id, invalid_message:)
+            ],
+            key_generator: key_generator,
+            unavailable_message: "MCP request rate key is unavailable"
+          )
+          "#{KEY_PREFIX}#{digest}".freeze
+        end
+      end
+    end
+    private_constant :RateLimitKey
+  end
+end

data/app/models/hitch/mcp/registry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    # Explicit host allowlist for MCP tools. Subclasses declare named Tool
+    # classes; Internal::RegistryRuntime validates the declarations into a
+    # persistent snapshot and resolves tools per request.
+    class Registry
+      Declaration = Data.define(:class_name, :scopes, :source)
+
+      class << self
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@hitch_mcp_declarations, [].freeze)
+        end
+
+        def register(tool_class = nil, scopes: nil)
+          declaration = Declaration.new(
+            class_name: declaration_class_name(tool_class),
+            scopes: declaration_scopes(scopes),
+            source: declaration_source(tool_class)
+          )
+          @hitch_mcp_declarations = (declarations + [ declaration ]).freeze
+          tool_class
+        end
+
+        def declarations
+          @hitch_mcp_declarations ||= [].freeze
+        end
+
+        private
+
+        def declaration_class_name(tool_class)
+          name = tool_class.name if tool_class.respond_to?(:name)
+          name.is_a?(String) && !name.empty? ? name.dup.freeze : nil
+        end
+
+        # What the host actually wrote, kept for the boot error that fires
+        # when it was not a named class. By then class_name is already nil and
+        # only the entry's position is left, which makes a host with a dozen
+        # tools count down a list to find their own typo.
+        def declaration_source(tool_class)
+          case tool_class
+          when nil then "no argument"
+          when Class then named_or(tool_class, "an anonymous class")
+          when Module then named_or(tool_class, "an anonymous module")
+          else "#{tool_class.inspect} (a #{tool_class.class})"
+          end
+        rescue StandardError
+          # inspect is host code on an arbitrary object; a registry mistake
+          # must not surface as some unrelated exception from this method.
+          "a #{tool_class.class}"
+        end
+
+        def named_or(mod, fallback)
+          name = mod.name
+          name.is_a?(String) && !name.empty? ? name : fallback
+        end
+
+        def declaration_scopes(scopes)
+          return unless scopes.is_a?(Array)
+
+          scopes.map { |scope| scope.is_a?(String) ? scope.dup.freeze : nil }.freeze
+        end
+      end
+
+      private_constant :Declaration
+    end
+  end
+end

data/app/models/hitch/mcp/result.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    # Closed host return value for MCP tool execution. Constructors copy host
+    # values so later mutation cannot change the result Hitch validates.
+    class Result
+      RESULT_MESSAGES = {
+        recursive: "MCP Result contains a recursive value",
+        key: "MCP Result keys must be Strings",
+        duplicate_key: "MCP Result contains a duplicate key",
+        non_finite: "MCP Result contains a non-finite number",
+        foreign: "MCP Result must contain only JSON values"
+      }.freeze
+      private_constant :RESULT_MESSAGES
+
+      class << self
+        def text(value)
+          new(:text, copy_string(value), nil)
+        end
+
+        def structured(value, text: nil)
+          copied_text = text.nil? ? nil : copy_string(text)
+          new(:structured, copy_json(value), copied_text)
+        rescue SystemStackError
+          raise ArgumentError, "MCP Result nesting is too deep"
+        end
+
+        def error(public_message)
+          new(:error, copy_string(public_message), nil)
+        end
+
+        private
+
+        def copy_string(value)
+          raise ArgumentError, "MCP Result text must be a String" unless value.is_a?(String)
+
+          value.dup.freeze
+        end
+
+        def copy_json(value)
+          Internal::JsonValues.copy(
+            value,
+            keys: :string, symbols: :reject, foreign: :reject, finite: true,
+            duplicates: :reject, freeze: true,
+            on_invalid: ->(reason, _detail) { raise ArgumentError, RESULT_MESSAGES.fetch(reason) }
+          )
+        end
+      end
+
+      attr_reader :kind, :value, :text
+
+      def initialize(kind, value, text)
+        @kind = kind
+        @value = value
+        @text = text
+        freeze
+      end
+
+      private_class_method :new, :allocate
+    end
+  end
+end

data/app/models/hitch/mcp/tool.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Hitch
+  module MCP
+    # Declarative MCP tool descriptor. Registry admission, listing, and later
+    # execution resolve the current named subclass; instances are never needed.
+    class Tool
+      NOT_SET = Object.new.freeze
+      INVALID_DECLARATION = Object.new.freeze
+      ARGUMENT_MESSAGES = {
+        recursive: "recursive MCP tool arguments",
+        key: "MCP tool argument keys must be strings",
+        duplicate_key: "duplicate MCP tool argument key",
+        non_finite: "MCP tool arguments contain a non-finite number",
+        foreign: "MCP tool arguments must contain only JSON values"
+      }.freeze
+
+      class << self
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@tool_name, nil)
+          subclass.instance_variable_set(:@description, nil)
+          subclass.instance_variable_set(:@input_schema, nil)
+          subclass.instance_variable_set(:@output_schema, nil)
+          subclass.instance_variable_set(:@annotations, nil)
+        end
+
+        def tool_name(value = NOT_SET)
+          return @tool_name if value.equal?(NOT_SET)
+
+          @tool_name = copy_declaration(value)
+        end
+
+        def description(value = NOT_SET)
+          return @description if value.equal?(NOT_SET)
+
+          @description = copy_declaration(value)
+        end
+
+        def input_schema(value = NOT_SET, **keywords)
+          return @input_schema if value.equal?(NOT_SET) && keywords.empty?
+
+          @input_schema = copy_declaration(combine_value_and_keywords(value, keywords))
+        end
+
+        def output_schema(value = NOT_SET, **keywords)
+          return @output_schema if value.equal?(NOT_SET) && keywords.empty?
+
+          @output_schema = copy_declaration(combine_value_and_keywords(value, keywords))
+        end
+
+        def annotations(value = NOT_SET, **keywords)
+          return @annotations if value.equal?(NOT_SET) && keywords.empty?
+
+          @annotations = copy_declaration(combine_value_and_keywords(value, keywords))
+        end
+
+        # Coarse request-local admission. Host applications must opt each tool
+        # in explicitly.
+        def available_to?(_context)
+          false
+        end
+
+        # Argument-aware host policy is deny-default. Its return value is not an
+        # authority signal: allowing means returning without raising.
+        def authorize!(_context, arguments:)
+          raise Forbidden
+        end
+
+        # Host behavior runs only after availability, static scope, SDK schema,
+        # and argument-aware policy have all admitted the invocation.
+        def perform(_context, arguments:)
+          raise "MCP tool perform must be implemented"
+        end
+
+        # This SDK-facing boundary is final. Registry validation rejects any
+        # subclass that replaces it, so every invocation follows the same
+        # context extraction, argument normalization, policy, host, and Result
+        # normalization order.
+        def call(server_context:, **sdk_arguments)
+          phase = :context
+          invocation = nil
+          reporting_tool_name = tool_name
+          context = server_context.fetch(:hitch_context)
+          phase = :arguments
+          arguments = normalize_arguments(sdk_arguments)
+          invocation = Internal::Observation.start_invocation(tool_name: reporting_tool_name)
+          phase = :authorization
+          authorize!(context, arguments:)
+          invocation&.argument_policy_allowed!
+          phase = :execution
+          invocation&.execution_started!
+          result = perform(context, arguments:)
+          phase = :result
+          normalized = Internal::ResultNormalizer.call(
+            result:,
+            output_schema: output_schema,
+            max_bytes: Hitch.configuration.mcp.max_result_bytes
+          )
+          invocation&.result_normalized!(kind: result.kind)
+          normalized
+        rescue StandardError, SystemStackError => error
+          invocation&.failed!(
+            phase:,
+            expected_denial: phase == :authorization && error.is_a?(Hitch::MCP::Forbidden)
+          )
+          Internal::ErrorNormalizer.call(
+            error:,
+            phase:,
+            context:,
+            tool_name: reporting_tool_name
+          )
+        ensure
+          invocation&.finish!
+        end
+
+        private
+
+        def normalize_arguments(value)
+          Internal::JsonValues.copy(
+            value,
+            keys: :stringify_symbols, symbols: :reject, foreign: :reject,
+            finite: true, duplicates: :reject, freeze: true,
+            on_invalid: ->(reason, _detail) { raise ArgumentError, ARGUMENT_MESSAGES.fetch(reason) }
+          )
+        end
+
+        # The setter path guards against value and keywords both being absent,
+        # so one of the two is always present here.
+        def combine_value_and_keywords(value, keywords)
+          keywords.empty? ? value : keywords
+        end
+
+        def copy_declaration(value)
+          Internal::JsonValues.copy(
+            value,
+            keys: :preserve, foreign: :reject, duplicates: :reject, freeze: true,
+            on_invalid: ->(_reason, _detail) { INVALID_DECLARATION }
+          )
+        end
+      end
+
+      private_constant :NOT_SET, :INVALID_DECLARATION, :ARGUMENT_MESSAGES
+    end
+  end
+end

data/app/models/hitch/oauth_request_parameters.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Hitch
+  class OauthRequestParameters
+    # Deliberately not an ArgumentError: the rescue below converts decoding
+    # ArgumentErrors into Invalid, and must never catch its own product.
+    class Invalid < StandardError; end
+
+    FORM_MEDIA_TYPE = "application/x-www-form-urlencoded"
+
+    def initialize(request, allowed:, form_only: false)
+      @request = request
+      @allowed = allowed.map(&:to_s).freeze
+      @form_only = form_only
+    end
+
+    def to_h
+      query = query_pairs
+      reject_query_security_parameters!(query) if form_only
+      pairs = (form_only ? [] : query) + form_pairs
+      reject_nested_security_parameters!(pairs)
+
+      allowed.to_h do |name|
+        values = pairs.filter_map { |key, value| value if key == name }
+        raise Invalid, "#{name} must not be repeated" if values.length > 1
+        raise Invalid, "#{name} must be a string" if values.any? { |value| !value.is_a?(String) }
+        raise Invalid, "#{name} must not be blank" if values.one? && values.first.blank?
+
+        [ name.to_sym, values.first&.dup&.freeze ]
+      end.freeze
+    rescue ArgumentError
+      raise Invalid, "OAuth parameters are not valid form encoding"
+    end
+
+    private
+
+    attr_reader :request, :allowed, :form_only
+
+    def query_pairs
+      decode(request.query_string)
+    end
+
+    def form_pairs
+      return [] unless request.post? && request.media_type == FORM_MEDIA_TYPE
+
+      decode(request.raw_post)
+    end
+
+    def decode(value)
+      return [] if value.blank?
+
+      URI.decode_www_form(value)
+    end
+
+    def reject_nested_security_parameters!(pairs)
+      pairs.each do |key, _value|
+        root = key.to_s.split("[", 2).first
+        next unless allowed.include?(root)
+        next if key == root
+
+        raise Invalid, "#{root} must be a scalar string"
+      end
+    end
+
+    def reject_query_security_parameters!(pairs)
+      pairs.each do |key, _value|
+        root = key.to_s.split("[", 2).first
+        next unless allowed.include?(root)
+
+        raise Invalid, "#{root} must be sent in the form body"
+      end
+    end
+  end
+end

data/app/views/hitch/authorizations/new.html.erb

@@ -0,0 +1,57 @@
+<%# Default consent screen. Host apps override by placing
+   app/views/hitch/authorizations/new.html.erb in their own
+   tree. The host's layout wraps this template automatically. %>
+
+<div class="hitch-rails-consent">
+  <h1>Authorize <%= @client_name %></h1>
+  <p>
+    <strong><%= @client_name %></strong>
+    (<%= @redirect_host %>)
+    is requesting access to your <%= @brand_name %> account.
+  </p>
+
+  <% if @localhost_only_client %>
+    <p class="hitch-rails-consent__warning">
+      <strong>This application runs on your own computer.</strong>
+      It will receive access at <code><%= @redirect_host %></code>, so
+      approve it only if you started it yourself and recognise it.
+    </p>
+  <% end %>
+
+  <% if @scopes.present? %>
+    <div class="hitch-rails-consent__scopes">
+      <p>It will be granted the following access:</p>
+      <ul>
+        <% @scopes.split(/\s+/).each do |scope| %>
+          <li><code><%= scope %></code></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <% if @resource.present? %>
+    <p class="hitch-rails-consent__resource">
+      Resource: <code><%= @resource %></code>
+    </p>
+  <% end %>
+
+  <%# turbo: false forces a real browser navigation. The controller
+     redirects to the client's redirect_uri (a cross-origin host, e.g.
+     https://grok.com/...); Turbo Drive submits via fetch and CANNOT
+     follow a cross-origin 302, so the redirect is swallowed and the
+     buttons appear to do nothing. A full-page submit lets the browser
+     follow the redirect and deliver the response to the client. %>
+  <%= form_with url: oauth_authorize_path, method: :post, data: { turbo: false } do |f| %>
+    <% @oauth_params.each do |key, value| %>
+      <% next if value.blank? %>
+      <%= hidden_field_tag key, value %>
+    <% end %>
+
+    <button type="submit" class="hitch-rails-consent__approve">
+      Approve
+    </button>
+    <button type="submit" name="decision" value="deny" class="hitch-rails-consent__deny">
+      Deny
+    </button>
+  <% end %>
+</div>

data/config/routes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+Hitch::Engine.routes.draw do
+  # OAuth dance
+  get  "oauth/authorize", to: "authorizations#new",   as: :oauth_authorize
+  post "oauth/authorize", to: "authorizations#create"
+  post "oauth/token",     to: "tokens#create",        as: :oauth_token
+  post "oauth/register",  to: "registrations#create", as: :oauth_register
+  post "oauth/revoke",    to: "revocations#create",   as: :oauth_revoke
+
+  # Route only real engine endpoints to the dedicated preflight validator.
+  match "oauth/authorize", to: "preflights#show", via: :options, defaults: { target_methods: "GET,POST" }
+  match "oauth/token",     to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
+  match "oauth/register",  to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
+  match "oauth/revoke",    to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
+
+  # Discovery (RFC 8414 + RFC 9728)
+  get ".well-known/oauth-authorization-server", to: "metadata#show",     as: :oauth_authorization_server_metadata
+  get ".well-known/oauth-protected-resource",   to: "metadata#resource", as: :oauth_protected_resource_metadata
+
+  # RFC 9728 §3.1: a resource served at a path (e.g. /mcp) publishes its
+  # metadata at the PATH-AWARE well-known URI. Strict clients (Grok)
+  # request /.well-known/oauth-protected-resource/<path> FIRST, then fall
+  # back to the bare variant — without this route that first probe 404s.
+  # The gem serves a single configured resource, so the captured path is
+  # ignored and the same document is returned. `format: false` keeps a
+  # dotted resource path from being parsed as a response format. Declared
+  # after the bare route (glob-last).
+  get ".well-known/oauth-protected-resource/*resource_path", to: "metadata#resource", format: false
+
+  match ".well-known/oauth-authorization-server", to: "preflights#show", via: :options,
+    defaults: { target_methods: "GET" }
+  match ".well-known/oauth-protected-resource", to: "preflights#show", via: :options,
+    defaults: { target_methods: "GET" }
+  match ".well-known/oauth-protected-resource/*resource_path", to: "preflights#show", via: :options,
+    defaults: { target_methods: "GET" }, format: false
+end

data/db/migrate/20260817000000_create_hitch_tables.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class CreateHitchTables < ActiveRecord::Migration[7.2]
+  def change
+    create_table :hitch_access_tokens do |t|
+      # Polymorphic principals may use integer, UUID, ULID, or other
+      # string-shaped primary keys. A numeric foreign-key column silently
+      # truncates those values on SQLite and rejects them on PostgreSQL, so
+      # keep the shared representation lossless and let each principal model
+      # cast its own primary key when Rails resolves the association.
+      t.references :principal, polymorphic: true, type: :string, null: false, index: true
+
+      t.string :client_id, null: false
+      t.string :client_name
+
+      # The raw authorization code is returned to the client once, in the
+      # OAuth redirect; only its SHA256 digest is at rest — the same
+      # posture as bearer tokens.
+      t.string :authorization_code_digest,
+        index: { unique: true, where: "authorization_code_digest IS NOT NULL" }
+      t.datetime :code_expires_at
+      t.string :redirect_uri
+
+      t.string :code_challenge, null: false
+      t.string :code_challenge_method, null: false, default: "S256"
+
+      t.string :token_digest, index: { unique: true, where: "token_digest IS NOT NULL" }
+      t.datetime :expires_at
+      t.datetime :revoked_at
+
+      t.string :resource_uri
+      t.string :scopes, null: false, default: "mcp"
+
+      t.timestamps
+    end
+
+    create_table :hitch_clients do |t|
+      t.string :client_id, null: false, index: { unique: true }
+      t.string :client_name, null: false
+
+      # OpenID Connect DCR 1.0 §2. Nullable and deliberately NOT defaulted
+      # to "web": NULL means "did not declare", which is the fact worth
+      # recording — a future decision to gate loopback redirects on
+      # application_type must be able to see who actually said "native".
+      t.string :application_type
+
+      t.string :token_endpoint_auth_method, null: false, default: "none"
+      t.string :client_secret_digest
+      t.datetime :client_secret_issued_at
+      t.datetime :client_secret_rotated_at
+
+      t.timestamps
+
+      t.check_constraint "token_endpoint_auth_method IN ('none', 'client_secret_basic')",
+        name: "hitch_clients_auth_method_check"
+      t.check_constraint <<~SQL.squish, name: "hitch_clients_secret_consistency_check"
+        (token_endpoint_auth_method = 'none' AND client_secret_digest IS NULL AND client_secret_issued_at IS NULL AND client_secret_rotated_at IS NULL)
+        OR
+        (token_endpoint_auth_method = 'client_secret_basic' AND client_secret_digest IS NOT NULL AND client_secret_issued_at IS NOT NULL)
+      SQL
+    end
+
+    create_table :hitch_client_redirect_uris do |t|
+      t.references :hitch_client,
+        null: false,
+        index: false,
+        foreign_key: { to_table: :hitch_clients, on_delete: :cascade }
+      t.string :uri, null: false
+
+      t.timestamps
+
+      t.index [ :hitch_client_id, :uri ],
+        unique: true,
+        name: "index_hitch_client_redirect_uris_on_client_and_uri"
+    end
+  end
+end

data/docs/operator/doctor.md

@@ -0,0 +1,82 @@
+# Hitch doctor
+
+`hitch:doctor` is a read-only installation diagnostic for the current Rails
+environment. Run it after installation, before a deploy, and whenever routing,
+discovery, registry loading, or request admission behaves differently than the
+host expects:
+
+```sh
+bin/rails hitch:doctor
+```
+
+The default human output has one stable row per check, plus an indented
+`->` line naming the fix for any check that did not pass. Machine consumers
+select the versioned JSON document explicitly:
+
+```sh
+HITCH_DOCTOR_FORMAT=json bin/rails hitch:doctor
+```
+
+The only accepted formats are `human` and `json`. The process exits zero when
+all findings are `pass`, `skip`, or `warn`; any `fail` finding exits one after
+the complete report is printed. Warnings identify a supported but non-golden
+posture, such as an unshared cache store in development/test, an empty
+explicit Registry, or plain-HTTP browser origins in production.
+
+## Stable check categories
+
+The JSON schema identifier is `hitch.doctor.v1`. Its `checks` array always has
+these IDs in this order:
+
+1. `versions` — loaded Hitch, Ruby, Rails, and MCP versions are inside the
+   packaged support window.
+2. `configuration` — the current OAuth configuration is valid and any enabled
+   MCP runtime has all required settings. Production DCR also requires its
+   resolved rate store (default: `config.cache_store`) to count across
+   processes.
+3. `resource_discovery` — internal requests to both discovery documents agree
+   with the canonical resource URI and issuer. No external network request is
+   made.
+4. `route_order` — exactly one modern MCP endpoint owns the canonical path,
+   admits its full method contract, precedes one root Hitch engine mount, and is
+   not shadowed. Auth-only mode skips this MCP-only check.
+5. `migrations` — every packaged Hitch migration has run and every required
+   table exists.
+6. `registry` — the configured Registry resolves and validates atomically. An
+   empty Registry warns because no tool is exposed; auth-only mode skips it.
+7. `hosts` — Rails host authorization accepts the canonical resource host and
+   every additional exact Hitch host.
+8. `origins` — browser CORS is deny-default or uses exact configured origins.
+   Plain-HTTP browser origins warn in production.
+9. `rate_limit_store` — one isolated diagnostic key increments twice against
+   the configured admission store, returns `1` then `2`, and is removed. It
+   never uses Hitch's application quota-key namespace. A store that cannot
+   count, or one that cannot count across processes, fails in production and
+   warns elsewhere; auth-only mode skips it.
+
+Every check names something the host can act on. Gem-self-diagnosis (packaged
+file integrity) lives in this repository's CI, not here. The `versions` bounds
+are read from the loaded gemspec, so the report can never disagree with the
+gem's declared support window.
+
+Each check has `status`, stable `code`, human `summary`, and bounded structural
+`details`. Exception messages, credentials, bearer values, request bodies,
+store credentials, and diagnostic keys are never reported. The admission-store
+check reports the store class, whether it is shared across processes, and the
+two probe counts — as integers, nil, or a class name, never message text.
+
+## No repair mode
+
+Doctor does not edit configuration, routes, Registry declarations, migrations,
+or application data. Its internal discovery requests are GETs against the
+loaded Rack application. The store probes are the only writes: the
+`rate_limit_store` check increments a random `hitch:doctor:v1:*` key twice on
+the configured cache store with a five-second expiry, asserts the counts come
+back `1` then `2`, and deletes the key; when production DCR is enabled, the
+`configuration` check increments one such key on the registration store,
+requires an integer count, and deletes it. That namespace is distinct from
+Hitch's HMAC rate-limit keys.
+
+Fix the named host artifact and rerun the command. Do not parse the human prose
+for automation; parse `hitch.doctor.v1` JSON by check `id`, `status`, and
+`code`.