hitch-rails 0.2.0 → 0.3.0

data/db/migrate/20260822000000_add_hitch_refresh_tokens.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class AddHitchRefreshTokens < ActiveRecord::Migration[7.2]
+  def change
+    change_table :hitch_access_tokens, bulk: true do |t|
+      # Same posture as every other secret here: the raw token is returned
+      # once and only its SHA256 digest is at rest.
+      t.string :refresh_token_digest
+      # Idle window. Clamped at mint to the family ceiling, so one comparison
+      # answers "still usable" and no caller has to remember the ceiling.
+      t.datetime :refresh_expires_at
+      # The reuse-detection evidence. A consumed row is what tells a replayed
+      # token apart from a first use, so this is the one column cleanup must
+      # not collect while the family it belongs to is still live.
+      t.datetime :refresh_consumed_at
+
+      # The lineage. Every rotation inserts a new row carrying the family_id
+      # it descended from, so detecting one replay can revoke the whole line
+      # in a single statement. Deliberately a grouping key and not a parent
+      # pointer: revocation is family-wide, detection is per-digest, and
+      # nothing reads the tree. A column is additive later and permanent now.
+      t.string :family_id
+      # Absolute ceiling, copied unchanged down the lineage. Carried on each
+      # row rather than looked up from the root so rotation stays a single
+      # write and outlives the root being collected.
+      t.datetime :family_expires_at
+    end
+
+    add_index :hitch_access_tokens, :refresh_token_digest,
+      unique: true, where: "refresh_token_digest IS NOT NULL"
+    add_index :hitch_access_tokens, :family_id, where: "family_id IS NOT NULL"
+  end
+end

data/docs/public_api/{0.2.0.md → 0.3.0.md}

@@ -1,9 +1,12 @@
-# hitch-rails 0.2 public API
+# hitch-rails 0.3 public API
 
-This file documents the `0.2.0` compatibility surface — the gem's first
-public release. The authenticated `Hitch::MCP::Endpoint` is the only MCP
-endpoint: it is stateless POST/OPTIONS, and it performs no notification/202
-response shaping.
+This file documents the `0.3.0` compatibility surface. It is the `0.2.0`
+surface plus refresh-token issuance, rotation, and reuse detection; nothing
+from 0.2 was removed or renamed. Upgrading requires running one new migration
+— see [`docs/upgrading/0.2-to-0.3.md`](../upgrading/0.2-to-0.3.md).
+
+The authenticated `Hitch::MCP::Endpoint` is the only MCP endpoint: it is
+stateless POST/OPTIONS, and it performs no notification/202 response shaping.
 
 For a confidential token exchange, `client_secret_basic` remains the only
 supported secret-bearing method. The form may repeat the same scalar
@@ -271,6 +274,60 @@ to 90 days (capped at 3650 days), the first configured scope, and the
 applies `access_token_lifetime_seconds`. Disclosure writes once to a new
 `0600` file or an attached terminal, never to stdout.
 
+## Refresh tokens
+
+New in 0.3.0 and enabled by default — the one library fallback in this gem
+that is on rather than off. `config.refresh_tokens_enabled = false` closes the
+grant entirely, and the flag guards exposure rather than whether the feature
+does its job: an access token lives an hour, so without renewal a hosted
+client's only recovery is the full consent redirect.
+
+The token endpoint accepts `grant_type=refresh_token` with `refresh_token`,
+`client_id`, `resource`, and an optional `scope`. Successful responses at both
+grants carry a `refresh_token` key whenever the feature is enabled; a client
+must not read its absence as an error. `grant_types_supported` in
+authorization-server metadata is derived from the flag through
+`Hitch::GrantTypes.supported`, so discovery never advertises a grant the
+endpoint refuses.
+
+Every use rotates: the presented token is consumed and a successor pair
+issued, per the OAuth 2.1 BCP's mandatory rotation for public clients.
+Rotation inserts a new row sharing a `family_id` with the authorization it
+descends from. Presenting an already-consumed token past
+`refresh_token_replay_grace_seconds` revokes the entire family, access tokens
+included; inside that window it is treated as an honest retry of a lost
+response and rotates again. A mismatched `client_id` is `invalid_grant` with
+nothing revoked. A refresh may narrow the granted scopes and never widen them
+(`invalid_scope`). `POST /oauth/revoke` accepts either token type: an access
+token revokes itself, a refresh token revokes its family.
+
+Settings, all on `Hitch::Configuration`:
+
+- `refresh_tokens_enabled=` accepts `true` or `false`, default `true`.
+- `refresh_token_lifetime_seconds=` accepts a positive Integer, default
+  `2_592_000` (30 days). The idle window for one refresh token, reset by every
+  rotation.
+- `refresh_token_replay_grace_seconds=` accepts `0` to `3_600`, default `60`.
+  Zero is strict one-time-use.
+- `refresh_token_family_lifetime_seconds=` accepts a positive Integer or
+  `nil`, default `nil`. An optional absolute ceiling on a family, fixed when
+  the family starts and never extended by rotation. Off by default because it
+  disconnects people who have done nothing wrong; the residual risk of
+  omitting it is documented in the README.
+
+`Hitch::AccessToken.exchange_refresh_token!(raw_refresh_token:, client_id:,
+resource_uri:, scopes:)`, `.find_by_refresh_token(raw)`, and
+`.revoke_family!(family_id)` are public and keep their names and arguments
+within 0.3.x, as do the instance predicates `family_expired?`,
+`honest_retry?`, and `narrowed_scopes`. `find_by_token` continues to read
+`token_digest` only: a refresh token is not an access token and never
+satisfies it.
+
+`cleanup_expired!` gained two floors. A row still holding a usable refresh
+token survives the retention window however long ago its access token lapsed,
+and a consumed row survives while it is still recent enough to be
+reuse-detection evidence. Both defer collection rather than cancelling it.
+
 `Hitch::MCP::Protocol` is framework-owned: it names the protocol version and
 method set for Hitch's own use, and may change with the profile Hitch
 implements. Host test suites pin `Hitch::MCP::TestHelper::PROTOCOL_VERSION`
@@ -279,7 +336,7 @@ instead.
 The operator tasks `hitch:doctor`, `hitch:cimd:check`,
 `hitch:clients:create_confidential`, `hitch:clients:rotate_secret`, and
 `Hitch::AccessToken.cleanup_expired!` are public and keep their names and
-arguments within 0.2.x.
+arguments within 0.3.x.
 
 The gem directly depends on `mcp >= 1.2, < 2` and `json_schemer >= 2.4, < 3`.
 It declares no Redis dependency. Hitch's SDK adapter, verified
@@ -314,9 +371,8 @@ claim and require separate approval.
 
 ## Distribution status
 
-All `0.2.0.pre.1` through `0.2.0.pre.4` artifacts are internal checkpoints.
-`0.2.0.pre.4` was the first public-eligible prerelease, and publication was
-deferred so final `0.2.0` can become the first public RubyGems release. No
-pre.4 tag, GitHub release, RubyGems publication, or downloaded-gem evidence
-exists. Every future tag, GitHub release, or RubyGems publication still
-requires an explicit maintainer decision after its milestone gates pass.
+`0.2.0` is published on RubyGems and is the first public release. `0.3.0` is
+prepared on `main` and unreleased: the version is bumped and this document is
+current, but no `v0.3.0` tag or RubyGems publication exists yet. Every tag,
+GitHub release, or RubyGems publication requires an explicit maintainer
+decision after its gates pass.

data/docs/upgrading/0.2-to-0.3.md

@@ -0,0 +1,180 @@
+# Upgrading hitch-rails 0.2 → 0.3
+
+This upgrade adds refresh tokens. It requires **one new migration** and no
+configuration changes. Written to be executed directly, by a person or by an
+agent working in the host application.
+
+## What you are changing, in one paragraph
+
+In 0.2 an MCP client's access token lasted an hour and there was no way to
+renew it, so a connector's only recovery was sending its human back through
+the OAuth consent screen. 0.3 issues a refresh token beside the access token
+and accepts `grant_type=refresh_token`, so the client renews itself in the
+background. Refresh tokens rotate on every use and a replayed one revokes the
+whole grant family. The feature is **on by default**.
+
+## Before you start
+
+Confirm you are actually on 0.2.x and that the working tree is clean:
+
+```bash
+bundle list | grep hitch-rails     # expect 0.2.x
+git status --porcelain             # expect empty
+```
+
+If the app is already on 0.3.x, stop — this guide does not apply.
+
+## Step 1 — point at 0.3
+
+**If 0.3.0 is published on RubyGems:**
+
+```ruby
+# Gemfile
+gem "hitch-rails", "~> 0.3.0"
+```
+
+**If you are tracking `main` ahead of the release** (the expected path while
+0.3.0 is being dogfooded):
+
+```ruby
+# Gemfile
+gem "hitch-rails", github: "tylerklose/hitch-rails", branch: "main"
+```
+
+Pin to a SHA instead of `branch:` if you want a reproducible build. Then:
+
+```bash
+bundle install
+```
+
+## Step 2 — run the migration
+
+Hitch appends its migrations to your app's migration paths, so there is
+nothing to copy or generate:
+
+```bash
+bin/rails db:migrate
+```
+
+This applies `20260822000000_add_hitch_refresh_tokens`, which adds five
+columns and two indexes to `hitch_access_tokens`. It is additive — no existing
+column or index is altered, and the 0.2 migration is untouched.
+
+**Do not skip this step.** Refresh-token issuance is on by default and writes
+columns the migration adds, so on an unmigrated database the *authorization
+code exchange* fails — not just refresh. That breaks the whole OAuth flow.
+Rails raises `ActiveRecord::PendingMigrationError` in development and test,
+and `bin/rails hitch:doctor` reports it, but a production deploy that skips
+migrations will fail at runtime.
+
+## Step 3 — verify
+
+```bash
+bin/rails hitch:doctor
+```
+
+Expect `migrations` to report `current`. If it reports `missing`, step 2 did
+not run.
+
+Then confirm the grant is actually being advertised and honored:
+
+```bash
+# Discovery should now list refresh_token
+curl -s https://your-app.example.com/.well-known/oauth-authorization-server \
+  | grep -o '"grant_types_supported":\[[^]]*\]'
+# expect: "grant_types_supported":["authorization_code","refresh_token"]
+```
+
+If you have an integration test that completes a code exchange, assert the
+response now carries a `refresh_token` key. Hitch's own suite does this in
+`test/integration/refresh_token_flow_test.rb` if you want a model.
+
+## What might break in your app
+
+None of this is a required change, but check each:
+
+1. **Tests asserting the exact shape of the token response.** Successful
+   `/oauth/token` responses now include a `refresh_token` key. An assertion
+   like `assert_equal %w[access_token token_type expires_in scope], body.keys`
+   will fail. Loosen it or add the key.
+2. **Tests asserting `grant_types_supported`.** It is now
+   `["authorization_code", "refresh_token"]` rather than a single entry.
+3. **A snapshot or contract test over discovery metadata.** Same reason.
+4. **Anything that scheduled `Hitch::AccessToken.cleanup_expired!` and
+   asserted a row count.** Cleanup now keeps two classes of row past the
+   retention window (see below), so counts will differ.
+
+Nothing else in the 0.2 surface changed. No method was removed or renamed.
+
+## Decisions you may want to make
+
+Both are optional, and the defaults are deliberate. **If you are an agent
+performing this upgrade, do not change either without asking the human first**
+— they are security posture, not configuration cleanup.
+
+### Should refresh tokens be on?
+
+They are on by default. This is the only setting in the gem whose library
+fallback is `true`, because the flag guards *exposure*, not whether the
+feature does its job — a flag nobody flips leaves every connector nagging
+hourly. Turn it off only if a threat model calls for it:
+
+```ruby
+config.refresh_tokens_enabled = false
+```
+
+That also drops `refresh_token` from `grant_types_supported`, so clients stop
+being told about a door that is shut.
+
+### Should a grant have a hard cutoff?
+
+By default a grant continues as long as it keeps being used; one that stops
+being used lapses after the idle window (30 days). There is no absolute
+ceiling.
+
+The residual risk of that, stated plainly: rotation and reuse detection catch
+a thief the moment the legitimate client refreshes again, because the replay
+collides with a consumed token and the family dies. They cannot catch a theft
+where the legitimate client *never comes back* — nothing collides, so nothing
+trips the alarm, and the stolen token keeps working until someone revokes it
+through `/oauth/revoke`. If that case matters to you:
+
+```ruby
+config.refresh_token_family_lifetime_seconds = 90 * 86_400
+```
+
+Every family started after that carries the ceiling. Note the cost: a ceiling
+does not reset, so it disconnects people who have done nothing wrong — daily
+users included — the moment it passes.
+
+## Operational notes
+
+`cleanup_expired!` now keeps two things past `revoked_retention_days`: a row
+still holding a usable refresh token, and a consumed row recent enough to be
+reuse-detection evidence. Both are deferrals, not exemptions — rows are
+collected once the refresh token has expired and the evidence is older than
+the window. Expect a modestly larger `hitch_access_tokens` table, roughly one
+retention window's worth of rows per actively-refreshing connector.
+
+If that matters at your scale, lower `revoked_retention_days` or set a family
+ceiling.
+
+## Rolling back
+
+```bash
+bin/rails db:rollback     # drops the five columns and two indexes
+```
+
+Then restore the 0.2 constraint in your `Gemfile` and `bundle install`.
+
+Any refresh tokens already issued stop working, which clients handle by
+falling back to the full OAuth redirect — the 0.2 behaviour. Access tokens are
+unaffected and keep working until they expire normally. No data an adopter
+owns is lost; the dropped columns hold only Hitch's own token state.
+
+## Reference
+
+- [`CHANGELOG.md`](../../CHANGELOG.md) — the 0.3.0 entry
+- [`docs/public_api/0.3.0.md`](../public_api/0.3.0.md) — the full compatibility surface
+- README, "Refresh tokens" — rotation, families, reuse detection, and the
+  reasoning behind each default

data/lib/generators/hitch/install/templates/initializer.rb

@@ -37,4 +37,16 @@ Hitch.configure do |config|
   # reviewed and registered in app/tools/mcp_tool_registry.rb.
   config.mcp.enabled = true
   config.mcp.registry = "McpToolRegistry"
+
+  # A connected client renews itself in the background instead of asking the
+  # person again every hour. Nothing here is long-lived: the access token is
+  # an hour and is re-minted rather than extended, and the refresh token is
+  # replaced on every use. What continues is the grant, and it continues by
+  # being used — an unused one expires after 30 days.
+  #
+  # Uncomment to put a hard cutoff on a grant no matter how actively it is
+  # used. Off by default because it disconnects people who have done nothing
+  # wrong; set it if you want a stolen refresh token whose real client never
+  # returns to expire on a clock rather than waiting for a revocation.
+  # config.refresh_token_family_lifetime_seconds = 90 * 86_400
 end

data/lib/hitch/configuration.rb

@@ -12,6 +12,9 @@ module Hitch
   #   spec conformance.
   class Configuration
     MAX_RESOURCE_URI_BYTES = 2_048
+    # An hour. Past this the window stops being "the response was lost" and
+    # starts being a second life for a spent credential.
+    MAX_REPLAY_GRACE_SECONDS = 3_600
     MAX_SCOPES = 32
     MAX_SCOPE_BYTES = 64
     MAX_SCOPE_SET_BYTES = 255
@@ -86,6 +89,56 @@ module Hitch
     # @return [Integer]
     attr_accessor :authorization_code_lifetime_seconds
 
+    # Issue a refresh token alongside each access token, and accept
+    # grant_type=refresh_token at the token endpoint. Default true.
+    #
+    # The one setting in this file whose library fallback is ON. An access
+    # token lives an hour; without a refresh token a hosted client's only
+    # renewal is the full consent redirect, so a flag nobody flips leaves
+    # every adopter's connector asking the same human the same question every
+    # hour. The flag exists to let an adopter close the surface deliberately,
+    # not to decide whether the feature does its job.
+    # @return [Boolean]
+    attr_reader :refresh_tokens_enabled
+
+    # Idle window for one refresh token, in seconds. Default 2_592_000
+    # (30 days). Each rotation issues a successor with a fresh window, so a
+    # connector in regular use never reaches it and an abandoned one goes
+    # quiet on its own.
+    # @return [Integer]
+    attr_reader :refresh_token_lifetime_seconds
+
+    # Optional absolute ceiling on a refresh-token family, in seconds,
+    # counted from the authorization the family descends from and never
+    # extended by rotation. Default nil: no ceiling.
+    #
+    # A ceiling disconnects a person who has done nothing wrong. It does not
+    # reset, so someone using the app every day is cut off the moment it
+    # passes and made to consent again — which is the interruption this
+    # feature exists to remove, arriving on a timer instead of hourly. The
+    # idle window already retires what nobody is using.
+    #
+    # What a ceiling would still buy, for an operator who wants one: rotation
+    # and reuse detection catch a thief the moment the real client refreshes
+    # again, because the replay collides. They cannot catch a theft where the
+    # real client never comes back, so nothing ever collides. A ceiling ends
+    # that case on a clock; without one it ends at revocation.
+    # @return [Integer, nil]
+    attr_reader :refresh_token_family_lifetime_seconds
+
+    # How long after a refresh token is consumed a repeat presentation is
+    # read as an honest retry rather than a replay, in seconds. Default 60.
+    # Set 0 for strict one-time-use.
+    #
+    # A token request is a POST whose response can be lost — a sleeping
+    # laptop, a network handoff, a server restarting between commit and
+    # response. Without this window the client's retry is indistinguishable
+    # from a thief's replay, so a dropped packet revokes the family and logs
+    # a real user out with a theft alarm. Within it, the retry rotates again
+    # and returns a fresh pair.
+    # @return [Integer]
+    attr_reader :refresh_token_replay_grace_seconds
+
     # Accept an https URL as a client_id and fetch client metadata from
     # it (Client ID Metadata Documents, the successor to Dynamic Client
     # Registration in MCP 2026-07-28).
@@ -173,6 +226,16 @@ module Hitch
       Hitch::RateLimitStore.resolve(@dynamic_client_registration_rate_store)
     end
 
+    # Same boot-time shape as mcp.validate_rate_limit_store!, and for the same
+    # reason: the engine's initializer must not resolve the default store by
+    # way of ActionController::Base while the application is initializing.
+    def validate_dynamic_client_registration_rate_store!
+      Hitch::RateLimitStore.assert_shared_at_boot!(
+        @dynamic_client_registration_rate_store,
+        setting: Hitch::DynamicRegistrationRateLimit::SETTING
+      )
+    end
+
     def dynamic_client_registration_rate_store=(value)
       @dynamic_client_registration_rate_store = Hitch::RateLimitStore.validate!(
         value, setting: "config.dynamic_client_registration_rate_store"
@@ -194,6 +257,10 @@ module Hitch
       @supported_scopes = [ "mcp".freeze ].freeze
       @access_token_lifetime_seconds = 3600
       @authorization_code_lifetime_seconds = 600
+      @refresh_tokens_enabled = true
+      @refresh_token_lifetime_seconds = 30 * 86_400
+      @refresh_token_family_lifetime_seconds = nil
+      @refresh_token_replay_grace_seconds = 60
       @principal_method = :current_user
       @login_path = nil
       @client_id_metadata_enabled = false
@@ -294,6 +361,38 @@ module Hitch
         "Hitch.configuration.resource_uri is required; set it to the canonical MCP endpoint URI"
     end
 
+    def refresh_tokens_enabled=(value)
+      unless value == true || value == false
+        raise ArgumentError, "refresh_tokens_enabled must be true or false"
+      end
+
+      @refresh_tokens_enabled = value
+    end
+
+    def refresh_token_lifetime_seconds=(value)
+      @refresh_token_lifetime_seconds =
+        positive_lifetime_setting(value, "refresh_token_lifetime_seconds")
+    end
+
+    def refresh_token_family_lifetime_seconds=(value)
+      @refresh_token_family_lifetime_seconds = if value.nil?
+        nil
+      else
+        positive_lifetime_setting(value, "refresh_token_family_lifetime_seconds")
+      end
+    end
+
+    def refresh_token_replay_grace_seconds=(value)
+      seconds = integer_setting(value, "refresh_token_replay_grace_seconds")
+      # Zero is strict one-time-use, which is a posture rather than a mistake.
+      unless seconds >= 0 && seconds <= MAX_REPLAY_GRACE_SECONDS
+        raise ArgumentError,
+          "refresh_token_replay_grace_seconds must be 0 to #{MAX_REPLAY_GRACE_SECONDS}"
+      end
+
+      @refresh_token_replay_grace_seconds = seconds
+    end
+
     def dynamic_client_registration_limit=(value)
       unless value.respond_to?(:to_h)
         raise ArgumentError, "dynamic_client_registration_limit must contain :to and :within"
@@ -372,6 +471,18 @@ module Hitch
       false
     end
 
+    # A lifetime past AccessToken::MAX_LIFETIME_SECONDS overflows a Postgres
+    # timestamp and sorts before today on SQLite, which would hand an operator
+    # a credential that silently never resolves.
+    def positive_lifetime_setting(value, name)
+      seconds = integer_setting(value, name)
+      return seconds if seconds.positive? && seconds <= Hitch::AccessToken::MAX_LIFETIME_SECONDS
+
+      raise ArgumentError,
+        "#{name} must be a positive number of seconds, at most " \
+          "#{Hitch::AccessToken::MAX_LIFETIME_SECONDS}"
+    end
+
     def integer_setting(value, name)
       integer = if value.is_a?(Integer)
         value

data/lib/hitch/doctor.rb

@@ -85,6 +85,12 @@ module Hitch
       end
     end
 
+    # Rails host authorization answers a rejected Host with its HTML 403 page,
+    # which the discovery probe's JSON parser reported as a JSON::ParserError:
+    # one blocked host, two alarms, and the louder one naming a bug that does
+    # not exist. The middleware records the rejection on the env it was handed.
+    HostBlocked = Class.new(StandardError)
+
     class System
       REQUIRED_TABLES = %w[
         hitch_access_tokens
@@ -312,6 +318,8 @@ module Hitch
           "HTTPS" => ("on" if resource.scheme == "https")
         ).compact
         status, _headers, body = Rails.application.call(environment)
+        raise HostBlocked if environment["action_dispatch.blocked_hosts"]&.any?
+
         bytes = +""
         body.each do |part|
           bytes << part.to_s
@@ -505,6 +513,12 @@ module Hitch
       return pass("resource_discovery", "coherent", "Canonical resource and discovery documents agree", details) if coherent
 
       fail_check("resource_discovery", "mismatch", "Canonical resource and discovery documents do not agree", details)
+    rescue HostBlocked
+      skip(
+        "resource_discovery",
+        "host_blocked",
+        "Discovery probe cannot run while Rails host authorization blocks the canonical host"
+      )
     rescue StandardError => error
       probe_failure("resource_discovery", error)
     end
@@ -642,6 +656,6 @@ module Hitch
       fail_check(id, "probe_error", "The #{id.tr('_', ' ')} diagnostic could not complete", "error_class" => error.class.name)
     end
 
-    private_constant :Check, :Report, :System
+    private_constant :Check, :Report, :System, :HostBlocked
   end
 end

data/lib/hitch/engine.rb

@@ -28,6 +28,10 @@ module Hitch
 
     # Host apps see the engine's migrations via db:migrate without needing
     # to copy them — the install generator only writes the initializer.
+    #
+    # The corollary is that a shipped migration IS an adopter's migration, so
+    # editing one applies to fresh installs and silently skips every existing
+    # one. Append only; see docs/adr/0005-migration-append-only.md.
     initializer :append_migrations do |app|
       next if app.root.to_s == root.to_s
       # Skipped when ENGINE_ROOT is defined, which means the process was
@@ -95,10 +99,7 @@ module Hitch
 
       next unless Rails.env.production?
 
-      Hitch::RateLimitStore.assert_shared!(
-        configuration.dynamic_client_registration_rate_store,
-        setting: Hitch::DynamicRegistrationRateLimit::SETTING
-      )
+      configuration.validate_dynamic_client_registration_rate_store!
     end
 
     initializer "hitch.validate_configuration", after: :load_config_initializers do

data/lib/hitch/grant_types.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Which OAuth grants the token endpoint will actually accept right now.
+  #
+  # One source of truth on purpose. Discovery metadata advertising a grant is
+  # a promise a conformant client will act on, so a hardcoded
+  # `grant_types_supported` that drifted from the endpoint's real behaviour
+  # would send clients to a door this server answers with
+  # unsupported_grant_type.
+  module GrantTypes
+    module_function
+
+    def supported
+      types = [ "authorization_code" ]
+      types << "refresh_token" if Hitch.configuration.refresh_tokens_enabled
+      types.freeze
+    end
+  end
+end

data/lib/hitch/mcp/configuration.rb

@@ -122,10 +122,13 @@ module Hitch
       # Resolved separately from validate! because the application's cache store
       # is assembled by Rails' own initializers; this runs from to_prepare, once
       # config.cache_store is settled.
+      # The raw setting is passed, not the resolving reader: reading it here
+      # would ask ActionController::Base for the default store during
+      # initialization, which is the premature load this avoids.
       def validate_rate_limit_store!
         return true unless Rails.env.production?
 
-        Hitch::RateLimitStore.assert_shared!(rate_limit_store, setting: SETTING)
+        Hitch::RateLimitStore.assert_shared_at_boot!(@rate_limit_store, setting: SETTING)
       end
 
       # Framework lifecycle, not a host knob: the engine's to_prepare hook

data/lib/hitch/rate_limit_store.rb

@@ -35,6 +35,33 @@ module Hitch
             "config.cache_store (Solid Cache, Redis, Memcached) or set #{setting} explicitly."
       end
 
+      # The boot-time counterpart to resolve, for the two checks that run while
+      # the application is still initializing.
+      #
+      # resolve asks ActionController::Base for the default store, and touching
+      # that class during initialization is a premature load: Rails 8.2 logs a
+      # warning with a full backtrace on every boot, and Rails has been
+      # promoting that class of warning to errors.
+      #
+      # Deferring with on_load(:action_controller_base) is worse than the
+      # warning and was shipped once. That hook fires from run_load_hooks at
+      # the end of the class body, while cache_store is assigned later still,
+      # from inside the on_load(:action_controller) block that
+      # action_controller.set_configs registers. The store came back nil and
+      # killed the boot — in the fall-back case the deferral existed for.
+      #
+      # config.action_controller.cache_store is the same value
+      # ActionController::Base.cache_store reads, and reading configuration
+      # loads no controller and defers nothing, so an unshared store still
+      # fails the boot. The trailing Rails.cache mirrors what set_configs
+      # itself defaults to, so this does not depend on having run after it.
+      def assert_shared_at_boot!(configured, setting:)
+        store = configured ||
+          Rails.application.config.action_controller.cache_store ||
+          Rails.cache
+        assert_shared!(store, setting: setting)
+      end
+
       # MemoryStore is per process, NullStore retains nothing, and FileStore
       # reads and writes without a lock.
       def unshared?(store)

data/lib/hitch/version.rb

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

data/lib/hitch.rb

@@ -6,6 +6,7 @@ require "hitch/rate_limit_store"
 require "hitch/engine"
 require "hitch/resource_uri"
 require "hitch/pkce"
+require "hitch/grant_types"
 require "hitch/mcp/protocol"
 require "hitch/mcp/configuration"
 require "hitch/configuration"