hitch-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f06a693bf0801c38fec53dab3f46b4ce8cc5d0e362d39eafebdfaf9b13d1b1
-  data.tar.gz: 35259384a42618dc255dd3a05c06f71bdaca5e17067eacc6b08a1d7564ab10ae
+  metadata.gz: f5e84192f904de0068b0a3defad8e24fc016505b374d376574fec4a88a1d6ce4
+  data.tar.gz: dabd5731714cef7be235b377ffd89f831fb7f385d3e31d67395679b751d592de
 SHA512:
-  metadata.gz: '0803444dfe9b103310b55e5d154b1e139d17541506d9297a0b00d0774a070176240a46567cbe5c041ecc6c88fa80753dc48f40d508a2f5deabff81283a0b0fa5'
-  data.tar.gz: 22a5065e45a1ec72fe71a70a6bd24fb5c2c6cfbe6a1cda59e4fd581959899d0442dbded72c46a90752553404eb6f09e1502730bd5e96ceb69ce0c77469481202
+  metadata.gz: d114e3882f4ba5beb1a7bf467c9f66da01db784989e9c1b8d6efd3d0b7dda97871ff2959ba31a899cc12222a324150c6531394027a136ee1cd9342f3cbb7b210
+  data.tar.gz: 49aa9b3fe6450c1182768757878f76cc5ed380725a3e017384560a03fb855db1c8035a370b4157c581222a67635156e9da744782eba25f46bdfb21811623acd4

data/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to hitch-rails will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-22
+
+Upgrading from 0.2.0 requires running one new migration. See
+[`docs/upgrading/0.2-to-0.3.md`](docs/upgrading/0.2-to-0.3.md) — skipping it
+breaks the token endpoint, because refresh-token issuance is on by default and
+writes columns the migration adds.
+
+### Added
+
+- **Refresh tokens, with rotation and reuse detection.** The code exchange
+  issues a refresh token beside the access token, and `POST /oauth/token`
+  accepts `grant_type=refresh_token`. A connected MCP client now renews itself
+  in the background instead of sending its human back through the consent
+  screen every hour.
+
+  Every use rotates, per the OAuth 2.1 BCP's mandatory rotation for public
+  clients: the presented token is consumed and a successor issued. Rotations
+  descend from the authorization that started them as a *family*. Presenting
+  an already-consumed token is a replay — the whole family is revoked, access
+  tokens included. A mismatched `client_id` is an ordinary `invalid_grant`
+  with nothing revoked, so learning a token cannot log its owner out. A
+  refresh may narrow the granted scopes and never widen them.
+
+  `POST /oauth/revoke` now accepts either token type: an access token revokes
+  itself, a refresh token revokes its family.
+
+  **Enabled by default** — the one library fallback in this gem that is on
+  rather than off. The flag guards exposure, not whether the feature does its
+  job, and a flag nobody flips would leave every adopter's connector nagging
+  hourly. `config.refresh_tokens_enabled = false` closes the grant and drops
+  `refresh_token` from `grant_types_supported`.
+
+  Nothing here is long-lived: the access token is still an hour and is
+  re-minted rather than extended, the refresh token is replaced on every use,
+  and neither is stored — both are SHA-256 digests at rest. What continues is
+  the grant, and it continues by being used. An unused one lapses after the
+  idle window (30 days). There is no absolute ceiling by default;
+  `refresh_token_family_lifetime_seconds` sets one, and the README documents
+  the residual risk of leaving it off.
+
+- `config.refresh_tokens_enabled`, `config.refresh_token_lifetime_seconds`,
+  `config.refresh_token_replay_grace_seconds`, and
+  `config.refresh_token_family_lifetime_seconds`.
+- `Hitch::AccessToken.exchange_refresh_token!`, `.find_by_refresh_token`, and
+  `.revoke_family!`.
+- Migration `20260822000000_add_hitch_refresh_tokens` — five columns and two
+  indexes on `hitch_access_tokens`. Additive; the published
+  `20260817000000` migration is untouched.
+
+### Changed
+
+- `grant_types_supported` in authorization-server metadata is derived from the
+  refresh-token flag rather than hardcoded, so discovery never advertises a
+  grant the endpoint would refuse.
+- `Hitch::AccessToken.cleanup_expired!` keeps two classes of row past the
+  retention window: one still holding a usable refresh token, and one whose
+  consumed record is still recent enough to be reuse-detection evidence. Both
+  are deferrals — the rows are collected once the refresh token has expired
+  and the evidence is older than `revoked_retention_days`.
+
+### Fixed
+
+- The doctor no longer reports a phantom `resource_discovery: probe_error /
+  JSON::ParserError` when the real failure is `hosts: blocked`. Rails host
+  authorization answers the discovery probe with an HTML 403, which was fed to
+  a JSON parser; one blocked host produced two alarms and the louder one named
+  a parser bug that did not exist. The probe now recognizes the rejection and
+  reports `resource_discovery: skip / host_blocked`, leaving the hosts check to
+  carry the remedy. (#25)
+
+- Rails 8.2 no longer logs two premature-load warnings, each with a full
+  backtrace, on every boot. The production-only check that the rate-limit store
+  can count across processes resolved the default store by asking
+  `ActionController::Base` for it, which loads the controller stack while the
+  application is still initializing. It reads
+  `config.action_controller.cache_store` instead — the same value, without
+  loading a controller — so the check stays eager and an unshared store still
+  fails the boot rather than the first request. Both the MCP and
+  dynamic-registration checks were affected. (#27)
+
 ## [0.2.0] - 2026-08-22
 
 Initial public release: a mountable Rails engine that turns a Rails app into

data/README.md

@@ -291,8 +291,10 @@ end
 
 `mint_mcp_token` mints a real access token through the production
 authorization-code path for any persisted record your app signs in as;
-`post_mcp` builds the JSON-RPC envelope with the canonical Host and modern
-MCP headers; `mcp_headers(token:, method:)` is available for manual requests.
+`post_mcp` builds the JSON-RPC envelope with modern MCP headers and the Host
+and scheme your `resource_uri` declares — the endpoint matches the canonical
+resource exactly, so you never call `https!` yourself;
+`mcp_headers(token:, method:)` is available for manual requests.
 `rails g hitch:tool` generates a test in exactly this shape.
 
 ## Headless agents
@@ -329,6 +331,122 @@ that database access did not already carry.
 Refresh-token issuance is deliberately not implemented, so an expired agent
 token is reissued the same way.
 
+## Refresh tokens
+
+> **Upgrading from 0.2?** This feature adds a migration and is on by default.
+> See [docs/upgrading/0.2-to-0.3.md](docs/upgrading/0.2-to-0.3.md).
+
+
+An access token lives an hour, which is the right lifetime for a credential
+that might leak. Without a way to renew it, though, that hour is all a hosted
+client ever gets: when it lapses the connector's only move is the full OAuth
+redirect, and the human who already granted consent gets asked again. And
+again.
+
+So Hitch issues a refresh token alongside every access token and accepts
+`grant_type=refresh_token` at the token endpoint. Every use rotates: the
+presented token is consumed and a new pair is issued, per the OAuth 2.1
+BCP's mandatory rotation for public clients.
+
+**This is the one setting in the gem that defaults to on.** Everything else
+here is deny-default — tools are hidden until you register them, origins are
+refused until you list them. The flag is different because it guards
+*exposure*, not whether the feature does its job, and a flag nobody flips
+would leave every adopter's connector nagging hourly. Close it deliberately
+if your threat model wants it closed:
+
+```ruby
+  config.refresh_tokens_enabled = false
+```
+
+Turning it off also drops `refresh_token` from `grant_types_supported` in
+discovery metadata, so clients stop being told about a door that is shut.
+
+### Rotation, families, and reuse detection
+
+Every rotation descends from the authorization that started it, and those
+descendants form a *family*. If a refresh token that was already consumed is
+presented again by its own client, someone is replaying a spent credential —
+Hitch revokes the entire family, access tokens included. Revoking a refresh
+token at `/oauth/revoke` does the same thing, because the trust a human
+granted at the consent screen is the family, not one link in it.
+
+A different `client_id` presenting the token is an ordinary `invalid_grant`
+with nothing revoked. Otherwise anyone who learned a token could log its
+owner out.
+
+```ruby
+  config.refresh_token_lifetime_seconds = 30 * 86_400  # idle window
+  config.refresh_token_replay_grace_seconds = 60       # 0 = strict one-time-use
+```
+
+The idle window resets on every rotation, so a connector in regular use never
+reaches it and an abandoned one goes quiet on its own.
+
+### Nothing here is long-lived
+
+"The connection keeps working" is not the same as "a key lives forever," and
+it is worth being precise about which secrets exist and for how long. The
+access token lasts an hour and is **re-minted, never extended**. The refresh
+token is **replaced on every use** — the one presented is spent and a new one
+takes its place. Neither is stored: both are SHA-256 digests at rest.
+
+What continues is the *grant* — the thing the human approved on the consent
+screen — and it continues by being used. Stop using it and it lapses.
+
+### Putting a hard cutoff on a grant
+
+```ruby
+  config.refresh_token_family_lifetime_seconds = nil  # default: no cutoff
+```
+
+By default a grant continues as long as it keeps being used. One that stops
+being used dies after the idle window above. There is no third clock, and
+that is deliberate: an absolute ceiling does not reset, so it disconnects
+someone who has done nothing wrong — use the app every day and you are still
+cut off the moment it passes, and made to consent again. That is exactly the
+interruption this feature exists to remove, arriving on a timer instead of
+hourly.
+
+**The residual risk, plainly.** Rotation and reuse detection catch a thief
+the moment the legitimate client refreshes again: the replay collides with a
+consumed token and the whole family dies. They cannot catch the case where
+the legitimate client *never comes back* — nothing ever collides, so nothing
+trips the alarm. Without a cutoff, a refresh token stolen from a connector
+its owner has abandoned keeps working until someone revokes it, through
+`/oauth/revoke` or by the host destroying the grant.
+
+That case is the reason to set a cutoff, and if your threat model cares about
+it, set one:
+
+```ruby
+  config.refresh_token_family_lifetime_seconds = 90 * 86_400
+```
+
+Every family started after that carries it. A family's terms are fixed when
+it starts, so changing this neither ages nor reprieves families already
+running.
+
+For reference, this default matches what Google ships for published apps: no
+absolute clock, with grants ending by disuse, credential change, or
+revocation.
+
+### The grace window, and what it costs
+
+A token request is a POST whose response can be lost — a sleeping laptop, a
+network handoff, a server restarting between commit and response. Strict
+one-time-use cannot tell that client's retry from a thief's replay, so a
+dropped packet would revoke the family and log a real user out with a theft
+alarm. Within `refresh_token_replay_grace_seconds` a repeat presentation is
+read as that retry and gets a fresh pair instead.
+
+Worth stating plainly: inside that window a stolen token can be presented
+repeatedly, each time minting another live branch of the family. The window
+is the price of not logging people out over dropped packets, and 60 seconds
+is a narrow race for an attacker who must also already hold the token. Set it
+to `0` for strict one-time-use, and note that Ory Hydra — whose graceful
+rotation this follows — defaults the equivalent window off rather than on.
+
 ## Operator diagnosis
 
 ```sh
@@ -411,7 +529,19 @@ class CleanupMCPTokensJob < ApplicationJob
 end
 ```
 
-Idempotent; active tokens are never touched.
+Idempotent; active tokens are never touched. Two things also survive the
+retention window: a row still holding a usable refresh token, however long
+ago its access token lapsed, and a consumed row that is still recent enough
+to be reuse-detection evidence. Collecting the first would delete a
+credential the client is about to present; collecting the second would turn
+a replayed stolen token into an ordinary `invalid_grant` and lose the alarm.
+
+Both are deferrals, not exemptions — once the refresh token has expired and
+the evidence is older than `revoked_retention_days`, the rows go. That
+bounds a family to roughly one retention window of rows however long it
+keeps rotating. The residual: a replay of a token consumed longer ago than
+that window is still refused, but no longer raises the alarm. Raise
+`revoked_retention_days` if you want a longer memory.
 
 ## Customizing the consent view
 
@@ -450,7 +580,9 @@ The exact public surface is documented in
 
 ## Contributing
 
-Issues and PRs welcome — see [CONTRIBUTING.md](https://github.com/tylerklose/hitch-rails/blob/main/CONTRIBUTING.md). Spec
+Issues and PRs welcome — see [CONTRIBUTING.md](https://github.com/tylerklose/hitch-rails/blob/main/CONTRIBUTING.md)
+and [AGENTS.md](https://github.com/tylerklose/hitch-rails/blob/main/AGENTS.md)
+for how work gets done here. Spec
 conformance is the primary correctness bar; citations to the
 [MCP authorization spec](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
 and the underlying RFCs are appreciated.

data/app/controllers/hitch/metadata_controller.rb

@@ -16,7 +16,7 @@ module Hitch
         token_endpoint: canonical_endpoint("/oauth/token"),
         revocation_endpoint: canonical_endpoint("/oauth/revoke"),
         response_types_supported: [ "code" ],
-        grant_types_supported: [ "authorization_code" ],
+        grant_types_supported: Hitch::GrantTypes.supported,
         code_challenge_methods_supported: [ "S256" ],
         scopes_supported: Hitch.configuration.supported_scopes,
         token_endpoint_auth_methods_supported: Hitch::Client::TOKEN_ENDPOINT_AUTH_METHODS,

data/app/controllers/hitch/revocations_controller.rb

@@ -12,10 +12,7 @@ module Hitch
       return head :ok unless request.media_type == Hitch::OauthRequestParameters::FORM_MEDIA_TYPE
 
       token_value = oauth_parameters(:token, form_only: true)[:token]
-      if token_value.present?
-        access_token = Hitch::AccessToken.find_by_token(token_value)
-        access_token&.revoke!
-      end
+      revoke(token_value) if token_value.present?
 
       head :ok
     rescue Hitch::OauthRequestParameters::Invalid
@@ -24,6 +21,18 @@ module Hitch
 
     private
 
+    # RFC 7009 §2.1: the endpoint takes either token type. An access token
+    # revokes itself; a refresh token revokes the family it belongs to,
+    # because the trust a human granted at the consent screen is the family,
+    # and revoking one link would leave the rest of the chain usable.
+    def revoke(token_value)
+      access_token = Hitch::AccessToken.find_by_token(token_value)
+      return access_token.revoke! if access_token
+
+      refresh_token = Hitch::AccessToken.find_by_refresh_token(token_value)
+      Hitch::AccessToken.revoke_family!(refresh_token.family_id) if refresh_token
+    end
+
     def reject_oversized_oauth_form_body!
       head :ok
     end

data/app/controllers/hitch/tokens_controller.rb

@@ -19,6 +19,8 @@ module Hitch
       code_verifier
       resource
       redirect_uri
+      refresh_token
+      scope
     ].freeze
 
     def create
@@ -27,7 +29,22 @@ module Hitch
       end
 
       oauth = oauth_parameters(*TOKEN_PARAMETER_NAMES, form_only: true)
-      return oauth_error("invalid_request", "grant_type must be authorization_code") unless oauth[:grant_type] == "authorization_code"
+      case oauth[:grant_type]
+      when "authorization_code" then authorization_code_grant(oauth)
+      when "refresh_token" then refresh_token_grant(oauth)
+      else
+        oauth_error("invalid_request", "grant_type must be #{Hitch::GrantTypes.supported.join(' or ')}")
+      end
+    rescue Hitch::ClientAuthentication::Invalid => error
+      response.headers["WWW-Authenticate"] = 'Basic realm="oauth/token"' if error.http_status == :unauthorized
+      oauth_error(error.oauth_code, error.message, error.http_status)
+    rescue Hitch::AccessToken::OAuthError => e
+      oauth_error(e.oauth_code, e.description)
+    end
+
+    private
+
+    def authorization_code_grant(oauth)
       return oauth_error("invalid_request", "code is required") if oauth[:code].blank?
       return oauth_error("invalid_request", "code_verifier is required") if oauth[:code_verifier].blank?
       unless Hitch::Pkce.valid_verifier?(oauth[:code_verifier])
@@ -40,11 +57,7 @@ module Hitch
       resource = require_canonical_resource(oauth[:resource])
       return unless resource
 
-      client_id = Hitch::ClientAuthentication.resolve(
-        request: request,
-        body_client_id: oauth[:client_id],
-        body_secret_present: oauth[:client_secret].present?
-      )
+      client_id = resolved_client_id(oauth)
       result = Hitch::AccessToken.exchange_authorization_code!(
         raw_code: oauth[:code],
         code_verifier: oauth[:code_verifier],
@@ -55,21 +68,49 @@ module Hitch
 
       return oauth_error("invalid_grant", "Invalid or expired authorization code") if result.nil?
 
-      render json: {
+      render_token(result)
+    end
+
+    def refresh_token_grant(oauth)
+      return oauth_error("invalid_request", "refresh_token is required") if oauth[:refresh_token].blank?
+
+      resource = require_canonical_resource(oauth[:resource])
+      return unless resource
+
+      client_id = resolved_client_id(oauth)
+      result = Hitch::AccessToken.exchange_refresh_token!(
+        raw_refresh_token: oauth[:refresh_token],
+        client_id: client_id,
+        resource_uri: resource,
+        scopes: oauth[:scope]
+      )
+
+      return oauth_error("invalid_grant", "Invalid or expired refresh token") if result.nil?
+
+      render_token(result)
+    end
+
+    def resolved_client_id(oauth)
+      Hitch::ClientAuthentication.resolve(
+        request: request,
+        body_client_id: oauth[:client_id],
+        body_secret_present: oauth[:client_secret].present?
+      )
+    end
+
+    # One shape for both grants. A refresh_token key is present only when the
+    # feature is on, so a client cannot read the absence as an error.
+    def render_token(result)
+      body = {
         access_token: result[:raw_token],
         token_type: "Bearer",
         expires_in: Hitch.configuration.access_token_lifetime_seconds,
         scope: result[:scope]
       }
-    rescue Hitch::ClientAuthentication::Invalid => error
-      response.headers["WWW-Authenticate"] = 'Basic realm="oauth/token"' if error.http_status == :unauthorized
-      oauth_error(error.oauth_code, error.message, error.http_status)
-    rescue Hitch::AccessToken::OAuthError => e
-      oauth_error(e.oauth_code, e.description)
+      body[:refresh_token] = result[:raw_refresh_token] if result[:raw_refresh_token].present?
+      render json: body
     end
 
-    private
-
     # RFC 6749 section 5.1 requires token responses to be non-cacheable.
     # This hook runs in OauthFormAdmission before Rails instrumentation, so
     # successful exchanges and early admission failures get the same policy.

data/app/models/hitch/access_token.rb

@@ -61,6 +61,36 @@ module Hitch
       token_digest.present? && !expired? && !revoked?
     end
 
+    # The ceiling the whole lineage descends from. Never extended by
+    # rotation, so a chain someone is quietly refreshing forever still stops.
+    def family_expired?
+      family_expires_at.present? && family_expires_at < Time.current
+    end
+
+    # A consumed token presented again inside the grace window: the client
+    # asking for a reply it never received. Outside it, the same request is a
+    # replay of a spent credential and kills the family.
+    def honest_retry?(now = Time.current)
+      return false if refresh_consumed_at.nil?
+
+      refresh_consumed_at + Hitch.configuration.refresh_token_replay_grace_seconds.seconds >= now
+    end
+
+    # RFC 6749 §6: a refresh may narrow the granted scopes and may never
+    # widen them. Asking for nothing keeps what was granted.
+    def narrowed_scopes(requested)
+      granted = scopes.to_s.split(/\s+/)
+      asked = Array(requested).flat_map { |value| value.to_s.split(/\s+/) }.reject(&:empty?).uniq
+      return scopes.to_s if asked.empty?
+
+      widened = asked - granted
+      unless widened.empty?
+        raise OAuthError.new("invalid_scope", "Refresh may narrow scopes but not widen them")
+      end
+
+      asked.join(" ")
+    end
+
     # Space-delimited scope check per OAuth 2.1 §3.3. Hosts call this to
     # gate operations behind a specific scope the client requested at
     # consent — e.g. `token.scope?("write")` before mutating ops.
@@ -179,23 +209,126 @@ module Hitch
       record.send(:verify_pkce!, code_verifier)
       raw_token = SecureRandom.urlsafe_base64(32)
       now = Time.current
+      refresh = mint_refresh_attributes(now: now, family_id: nil, family_expires_at: nil)
       updated = where(
         id: record.id,
         authorization_code_digest: code_digest,
         token_digest: nil
       ).where("code_expires_at > ?", now).update_all(
-        token_digest: Digest::SHA256.hexdigest(raw_token),
-        authorization_code_digest: nil,
-        code_expires_at: nil,
-        expires_at: now + Hitch.configuration.access_token_lifetime_seconds.seconds,
-        updated_at: now
+        {
+          token_digest: Digest::SHA256.hexdigest(raw_token),
+          authorization_code_digest: nil,
+          code_expires_at: nil,
+          expires_at: now + Hitch.configuration.access_token_lifetime_seconds.seconds,
+          updated_at: now
+        }.merge(refresh.fetch(:columns))
       )
 
       return nil unless updated == 1
 
-      { raw_token: raw_token, scope: record.scopes }
+      { raw_token: raw_token, raw_refresh_token: refresh[:raw_refresh_token], scope: record.scopes }
     end
 
+    # RFC 6749 §6 / OAuth 2.1 §4.3. Consumes the presented refresh token and
+    # issues a successor pair, or refuses.
+    #
+    # Rotation is the same conditional state transition the authorization code
+    # already uses: consumption is the guard, so two concurrent refreshes race
+    # on one UPDATE and exactly one wins. The loser did not steal anything —
+    # it lands in the replay path below, where a just-consumed token is an
+    # honest retry.
+    def self.exchange_refresh_token!(raw_refresh_token:, client_id:, resource_uri:, scopes: nil)
+      unless Hitch.configuration.refresh_tokens_enabled
+        raise OAuthError.new("unsupported_grant_type", "Refresh tokens are not enabled")
+      end
+
+      digest = Digest::SHA256.hexdigest(raw_refresh_token.to_s)
+      record = find_by(refresh_token_digest: digest)
+      return nil unless record
+
+      # Before consumed-state, deliberately. A different client presenting
+      # this token is a mismatched grant, not a theft alarm — revoking a
+      # family on it would let anyone who learns a token log its owner out.
+      unless record.client_id == client_id
+        raise OAuthError.new("invalid_grant", "Refresh token was not issued to this client")
+      end
+      unless record.resource_uri == resource_uri
+        raise OAuthError.new("invalid_target", "resource does not match the authorized resource")
+      end
+      return nil if record.revoked? || record.family_expired?
+
+      now = Time.current
+      # Reuse detection runs before anything the request can get wrong, so a
+      # replay cannot dodge the alarm by also asking for a bad scope.
+      if record.refresh_consumed_at
+        unless record.honest_retry?(now)
+          revoke_family!(record.family_id)
+          raise OAuthError.new("invalid_grant", "Refresh token has already been used")
+        end
+
+        # Inside the window a repeat presentation is the client asking again
+        # for a reply it never got: a fresh pair off the same parent, not a
+        # revoked family.
+        return record.send(:issue_successor!, granted: record.narrowed_scopes(scopes), now: now)
+      end
+      return nil if record.refresh_expires_at.nil? || record.refresh_expires_at < now
+
+      granted = record.narrowed_scopes(scopes)
+      consumed = where(id: record.id, refresh_consumed_at: nil)
+        .update_all(refresh_consumed_at: now, updated_at: now)
+      # Lost the race to a concurrent refresh microseconds ago. That is the
+      # honest-retry case arriving by a different door, not a replay.
+      return nil unless consumed == 1
+
+      record.send(:issue_successor!, granted: granted, now: now)
+    end
+
+    # A consumed refresh token presented again by its own client, past the
+    # grace window, is a replay of a credential its owner already spent. The
+    # family is the blast radius: every row descended from that one
+    # authorization, revoked in a single statement.
+    def self.revoke_family!(family_id)
+      return 0 if family_id.blank?
+
+      where(family_id: family_id, revoked_at: nil).update_all(
+        revoked_at: Time.current, updated_at: Time.current
+      )
+    end
+
+    def self.find_by_refresh_token(raw_refresh_token)
+      return nil if raw_refresh_token.blank?
+
+      find_by(refresh_token_digest: Digest::SHA256.hexdigest(raw_refresh_token))
+    end
+
+    # Columns for a freshly minted refresh token. A root passes no family and
+    # starts one; a successor inherits both, so the ceiling is fixed by the
+    # authorization the line descends from and rotation can never extend it.
+    def self.mint_refresh_attributes(now:, family_id:, family_expires_at:)
+      return { columns: {}, raw_refresh_token: nil } unless Hitch.configuration.refresh_tokens_enabled
+
+      raw = SecureRandom.urlsafe_base64(32)
+      # A family's terms are fixed when it starts: a successor inherits the
+      # ceiling its line began with, including the usual absence of one.
+      configured = Hitch.configuration.refresh_token_family_lifetime_seconds
+      ceiling = family_expires_at || (now + configured.seconds if configured)
+      idle = now + Hitch.configuration.refresh_token_lifetime_seconds.seconds
+      {
+        raw_refresh_token: raw,
+        columns: {
+          refresh_token_digest: Digest::SHA256.hexdigest(raw),
+          # Clamped at mint, so "still usable" is one comparison and no caller
+          # has to remember the ceiling separately. Usually there is no
+          # ceiling and this is just the idle window.
+          refresh_expires_at: [ idle, ceiling ].compact.min,
+          refresh_consumed_at: nil,
+          family_id: family_id || SecureRandom.uuid,
+          family_expires_at: ceiling
+        }
+      }
+    end
+    private_class_method :mint_refresh_attributes
+
     def revoke!
       update!(revoked_at: Time.current)
     end
@@ -218,6 +351,26 @@ module Hitch
     #   3) Expired tokens (expires_at < now) older than
     #      `revoked_retention_days` — same audit-window argument.
     #
+    # Class 3 has two floors, because `expires_at` is the ACCESS token's
+    # clock — an hour — and says nothing about the refresh token beside it.
+    #
+    #   - A row still holding a usable refresh token is not dead, however
+    #     long ago its access token lapsed. Collecting it would delete a
+    #     credential the client is about to present.
+    #   - A consumed row is the evidence reuse detection reads. On the
+    #     schedule alone it went while its family was still being refreshed,
+    #     and a replayed stolen token then found nothing and degraded to an
+    #     ordinary invalid_grant — the alarm gone, silently, with no test
+    #     failing. Evidence is held for the same audit window as everything
+    #     else here.
+    #
+    # Both floors defer collection rather than cancelling it: once the
+    # refresh token has expired and the evidence is older than the window,
+    # the row goes. That bounds a long-lived family to one window's worth of
+    # rows however long it keeps rotating. The residual is stated in the
+    # README — a replay of a token consumed longer ago than the window is
+    # refused, but no longer raises the alarm.
+    #
     # Returns the number of rows deleted. Idempotent.
     #
     # Hosts schedule this via whatever background job framework they
@@ -234,7 +387,11 @@ module Hitch
       count = 0
       count += where(token_digest: nil).where("code_expires_at < ?", Time.current).delete_all
       count += where.not(revoked_at: nil).where("revoked_at < ?", cutoff).delete_all
-      count += where.not(expires_at: nil).where("expires_at < ?", cutoff).delete_all
+      count += where.not(expires_at: nil)
+        .where("expires_at < ?", cutoff)
+        .where("refresh_expires_at IS NULL OR refresh_expires_at < ?", Time.current)
+        .where("refresh_consumed_at IS NULL OR refresh_consumed_at < ?", cutoff)
+        .delete_all
       count
     end
 
@@ -255,6 +412,41 @@ module Hitch
 
     private
 
+    # One rotation: a new row carrying the family it descended from, active
+    # the moment it lands. The spent code_challenge is copied because the
+    # column is NOT NULL and validated — it records which authorization this
+    # line came from, which is true of every descendant.
+    def issue_successor!(granted:, now:)
+      raw_token = SecureRandom.urlsafe_base64(32)
+      refresh = self.class.send(
+        :mint_refresh_attributes,
+        now: now,
+        family_id: family_id,
+        family_expires_at: family_expires_at
+      )
+      successor = self.class.create!(
+        {
+          principal_type: principal_type,
+          principal_id: principal_id,
+          client_id: client_id,
+          client_name: client_name,
+          redirect_uri: redirect_uri,
+          resource_uri: resource_uri,
+          code_challenge: code_challenge,
+          code_challenge_method: code_challenge_method,
+          scopes: granted,
+          token_digest: Digest::SHA256.hexdigest(raw_token),
+          expires_at: now + Hitch.configuration.access_token_lifetime_seconds.seconds
+        }.merge(refresh.fetch(:columns))
+      )
+
+      {
+        raw_token: raw_token,
+        raw_refresh_token: refresh[:raw_refresh_token],
+        scope: successor.scopes
+      }
+    end
+
     def verify_pkce!(code_verifier)
       raise OAuthError.new("invalid_grant", "Authorization code expired") if code_expires_at.nil? || code_expires_at < Time.current