hitch-rails 0.2.0 → 0.4.0

data/docs/adr/0006-device-authorization-grant.md

@@ -0,0 +1,153 @@
+# ADR 0006: The device authorization grant's shape
+
+## Status
+
+Accepted with 0.4.0. Records the decisions behind the RFC 8628
+implementation that aren't obvious from reading it — the ones a future
+change would most plausibly get wrong by "simplifying."
+
+## Context
+
+The device flow is the headless leg of token acquisition: a client with no
+browser shows its human a short code, the human approves at a URL, the
+client polls for the token. Almost all of it rearranges machinery this gem
+already had — digest-at-rest codes, conditional-UPDATE single-use
+transitions, the host-session consent surface, fail-closed unauthenticated
+rate limiting, the real authorization-code exchange as the one token mint
+path. Six decisions were genuinely new. Each is recorded with the
+alternative it refused.
+
+## Decisions
+
+**User codes are 8 characters of Crockford base32, normalized on input.**
+~40 bits against the RFC's own worked example of ~34.5 (§5.1), from an
+alphabet whose decoding treats `O`/`0` and `I`/`L`/`1` as equal — so §6.1's
+"strip punctuation, avoid confusables" is a three-line normalization
+(`upcase`, strip non-alphanumerics, `tr("OIL", "011")`) instead of a
+warning to typists. The RFC's letters-only base-20 example was the
+alternative; it reads slightly better aloud and carries 5.5 fewer bits.
+Entropy is a term in the brute-force equation whose other term is the
+verification quota, which is why both device quotas fail closed: an
+uncountable store voids the arithmetic, so production refuses at the
+request, the boot, and the doctor rather than admitting uncounted guesses.
+
+**The verification page owns `/activate`, at the engine root.** §3.3.1
+wants a URI short enough to read off a screen and type on a phone;
+`/oauth/device` was the collision-proof alternative. The cost is real —
+host routes declared before the mount silently shadow engine routes, and
+"activate" is a plausible host route name — and is paid with documentation
+(README, upgrade guide) rather than with a worse URL for every adopter
+without the collision.
+
+**The server holds a fixed polling interval, and a rejected poll advances
+nothing.** `slow_down` is decided by one conditional UPDATE — claim the
+window if `last_polled_at` is at least an interval old — because the
+read-compare-write alternative lets two simultaneous polls both pass. Not
+stamping rejected polls is deliberate: stamping them would lock a
+client polling slightly-too-fast out *forever*, and buys no security —
+possessing the 256-bit device code already is the credential, so the
+window bounds load, not guessing. §3.5's escalating back-off is the
+client's obligation; this server's job is to answer `slow_down` truthfully
+and cheaply (a too-fast poll writes nothing).
+
+**The mint endpoint never resolves client metadata.** Every CIMD fetch in
+this gem happens on behalf of a signed-in, per-principal-rate-limited
+actor, and the fetcher applies no rate limit at all when the actor is
+blank — a branch that is unreachable today precisely because the authorize
+leg authenticates first. Fetching at the unauthenticated device endpoint
+would make that branch the front door: anyone on the internet driving
+outbound HTTPS to hosts they chose. So mint validates shape only (a
+registered client must exist; a CIMD reference is accepted as a string),
+and resolution happens on `/activate` where the approving person is the
+actor — the same trust structure as the authorize leg. The consequence is
+accepted openly: an unresolvable CIMD client yields a code whose
+activation screen says it cannot be verified and offers no Approve, and
+the grant expires rather than being auto-denied — a fetch failure is
+weather, and `access_denied` is a statement about the person's intent that
+weather must not be allowed to make. The same no-Approve answer covers the
+states the revoke gestures create mid-grant: a registered client deleted
+while its grant was pending, and a CIMD scheme switched off. The stored
+token-endpoint authentication method fixes which voucher the grant may use;
+live flags and registration races cannot reclassify it.
+
+**Consumption runs the real exchange and honors the mint-time scope clamp
+verbatim.** The grant's scopes are clamped to `supported_scopes` when the
+code is minted — so the consent screen can only ever show grantable
+scopes — and issued unchanged when the approved grant is exchanged, the
+`issue_successor!` posture. Re-validating at poll time (what
+`AccessToken.issue!` does internally, and why consumption doesn't call
+it — that, and it discards the refresh token and scope its own exchange
+returns) would turn an adopter's config tidying into token-endpoint 500s;
+silently re-narrowing would rewrite what the person approved with nobody
+deciding. Consent is evaluated once, at the moment it is given; later
+machinery transports it. Withdrawing access afterward has a name, and it
+is revocation, not a config edit.
+
+**A device grant needs a vouched client, and the screen shows only the
+voucher's word.** The consent screen's display signal — the redirect host —
+is safe there because the authorization code is *delivered* to that host:
+claiming claude.ai means claude.ai receives the code. The device flow
+delivers nothing to a redirect host, so a registered client's redirect URIs
+are pure self-assertion, and with open registration anyone could mint a
+grant and dress the phish as any brand the `client_names` table knows. The
+answer is structural: minting requires a client somebody real vouches for —
+a CIMD reference (its host earned by serving the document) or a
+confidential client the operator registered at a console (its provenance is
+stored, and its secret authenticates every machine leg) — and the grant stores that authentication
+method. The mint endpoint, activation screen, and polling endpoint must all
+agree with it, so a concurrent registration change cannot lend the grant a
+different voucher and deleting a client cannot downgrade an approved grant
+to public. The screen displays the voucher's word: document host, or
+operator-chosen name labeled as the operator's. A self-registered DCR client,
+public or confidential, is refused at the mint endpoint
+and independently refused verification on /activate, so the guarantee holds
+whichever door a grant came through. The rejected alternatives, both ways:
+CIMD-only was too strict (it amputates the operator-badged pattern — the
+classic RFC 8628 deployment — and every host without direct outbound 443),
+and approvable-with-a-warning was too weak (the §5.4 scam is precisely a
+warning label on an open door). Loosening later is compatible; do not
+loosen by restoring redirect-host branding, which is unverifiable here at
+any setting.
+
+A seventh decision is inherited rather than new: the
+`/activate` warning copy is a security control (§5.4). The flow's known
+abuse — a stranger sends you a code to approve — defeats every technical
+control here, because the grant is genuine; the page's plain words and its
+refusal to headline self-declared client names are what remain. Tests
+assert the copy's presence for that reason, and the README tells
+overriding hosts to keep its meaning.
+
+## Consequences
+
+- The user-code namespace only ever contains genuinely pending codes: the
+  decision UPDATE erases the digest, and mint retries the rare collision
+  with a live one instead of surfacing it (an unauthenticated 500 would be
+  a collision oracle).
+- A grant can never be approved-but-unowned, decided twice, or consumed before
+  approval. The principal binding rides in the same statement as the
+  decision, and database check constraints make those invalid states
+  unrepresentable even outside the model. The cross-adapter migration and
+  concurrency gate (`bin/ci-migrations`) pins this on SQLite and PostgreSQL.
+- An adopter who narrows `supported_scopes` mid-flight ships tokens with
+  the scopes the person actually approved. That is the intended reading of
+  the clamp, not a gap. The clamp lives in `DeviceGrant.mint!` itself, so
+  every caller — the endpoint or host code — mints only grantable scopes.
+- `expires_at` is the RFC 8628 lifetime of the device and user codes. Once it
+  passes, pending and approved grants answer `expired_token`; approval never
+  extends the bearer device code's lifetime.
+- `hitch_device_grants` rows are disposable: `DeviceGrant.cleanup_expired!`
+  deletes them a day past expiry (the issued token rows carry the audit
+  trail). The day is a floor for wire honesty, not evidence retention — a
+  polling client hears `expired_token` or `access_denied` regardless of
+  when the host's cleanup job runs — unlike access-token rows with their
+  reuse-detection floors.
+
+## Removal and verification
+
+The feature is one flag, one table, one controller pair, one grant branch.
+Disabling it returns 404s at both endpoints, `unsupported_grant_type` at
+the token endpoint, and removes both advertisements — asserted in
+`test/integration/device_authorization_endpoint_test.rb` and
+`device_token_grant_test.rb`. Removing it outright would be a migration
+dropping `hitch_device_grants` (append-only, per ADR 0005) plus deleting
+the controllers, model, limiter, and routes; nothing else depends on them.

data/docs/operator/doctor.md

@@ -31,9 +31,10 @@ 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.
+   MCP runtime has all required settings. Production DCR and device
+   authorization each require their resolved rate store (default:
+   `config.cache_store`) to count across processes and to return `1` then `2`
+   from two real increments on the same isolated key.
 3. `resource_discovery` — internal requests to both discovery documents agree
    with the canonical resource URI and issuer. No external network request is
    made.
@@ -72,10 +73,13 @@ 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.
+back `1` then `2`, and deletes the key. In production, the `configuration`
+check also increments one isolated key twice and deletes it on each enabled
+feature's resolved store: `config.dynamic_client_registration_rate_store`
+and `config.device_authorization_rate_store`. That namespace is distinct from
+Hitch's HMAC rate-limit keys. A failure names the exact setting and prescribes
+a shared cache store whose two increments return `1` then `2`; ordinary
+`Hitch.configuration.validate!` does not execute these live probes.
 
 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

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

@@ -1,9 +1,13 @@
-# hitch-rails 0.2 public API
+# hitch-rails 0.4 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.4.0` compatibility surface. It is the `0.3.0`
+surface plus the OAuth 2.0 Device Authorization Grant (RFC 8628), off by
+default; nothing from 0.3 was removed or renamed. Upgrading requires running
+three new migrations — see
+[`docs/upgrading/0.3-to-0.4.md`](../upgrading/0.3-to-0.4.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,15 +275,156 @@ 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.
+
+## Device authorization
+
+New in 0.4.0 and **off by default** — `config.device_authorization_enabled =
+true` opens it. It is the headless leg of token acquisition: a client with no
+browser POSTs `client_id` and `resource` (plus optional `scope`) to
+`POST /oauth/device_authorization` as a form and receives the RFC 8628 §3.2
+response. `resource` is required here as at every other leg — RFC 8707
+audience binding is this server's spine, and a token that skipped it at mint
+could never be exchanged. Minting requires a vouched client: a CIMD
+reference, or a confidential client the operator registered (with that
+provenance stored and authenticated by its secret, `client_secret_basic`); a self-registered DCR client is
+refused with `invalid_client` — `device_code`, `user_code` (formatted `XXXX-XXXX`),
+`verification_uri` (`{issuer}/activate`), `verification_uri_complete`,
+`expires_in`, and `interval`. The verification URI is always built from the
+configured issuer, never the request host.
+
+The user code is 8 characters of Crockford base32 (no I, L, O, U).
+Verification normalizes input — punctuation stripped, uppercased, `O`→`0` and
+`I`/`L`→`1` — so a person may type the code sloppily. The device code is a
+256-bit `SecureRandom` value; both are stored as SHA-256 digests only.
+
+`GET /activate` and `POST /activate` render inside the host's own layout and
+sign-in, exactly as the consent screen does: the host's session gates the
+page, and the approval binds `current_principal`. The confirmation displays
+only the voucher's word: a CIMD client is branded by its `client_id`'s own
+URL host mapped through `client_names` (a client claims a host by serving
+its document there), and an operator-registered confidential client by the
+name the operator chose, labeled as operator-registered. Redirect hosts —
+which this flow never delivers anything to — and clients' self-declared
+names never display. A client with no live voucher cannot be approved — a
+CIMD document that does not resolve (or a metadata scheme disabled since
+mint), a registered client deleted while its grant was pending, or a
+self-registered DCR client whose grant was created outside the endpoint;
+the grant is left to expire. The stored token-endpoint authentication method
+must also match the live voucher at mint and activation, so a concurrent
+registration change cannot lend a grant a different identity posture.
+The page's warning copy is part of RFC 8628 §5.4's phishing defense and
+overriding hosts should preserve its meaning. The mint endpoint never fetches
+a client metadata document; CIMD resolution happens on `/activate`, where the
+signed-in approver is the rate-limit actor.
+
+The token endpoint accepts
+`grant_type=urn:ietf:params:oauth:grant-type:device_code` with `device_code`,
+`client_id`, and `resource`, and answers per §3.5: `authorization_pending`,
+`slow_down` (the server holds a fixed interval; rejected polls do not advance
+the window), `access_denied`, `expired_token`, or the token response. A
+grant records the token-endpoint authentication method established at mint;
+polling must use the same method, and an expired approved grant cannot redeem.
+A successful exchange runs the ordinary authorization-code path, so the issued
+row is an ordinary token — revocable, audience-bound, digest-at-rest, with a
+refresh token whenever that feature is enabled. The grant's scopes are
+clamped to `supported_scopes` at mint and issued verbatim at exchange.
+`grant_types_supported` and `device_authorization_endpoint` are advertised
+only while the flag is on.
+
+Both device quotas fail closed and count through the host cache store:
+per-IP on the mint endpoint, per-principal on `/activate` verification. In
+production an uncountable store refuses the request (503), the boot (when
+the flag is on), and the doctor check.
+
+Settings, all on `Hitch::Configuration`:
+
+- `device_authorization_enabled=` accepts `true` or `false`, default `false`.
+- `device_code_lifetime_seconds=` accepts a positive Integer, default `600`.
+- `device_authorization_interval_seconds=` accepts a positive Integer,
+  default `5` — the §3.2 value clients assume when `interval` is absent.
+- `device_authorization_limit=` accepts `{ to:, within: }` positive
+  Integers, default `{ to: 20, within: 60 }` (per-IP mint quota).
+- `device_code_verification_limit=` accepts the same shape, default
+  `{ to: 10, within: 60 }` (per-principal verification quota).
+- `device_authorization_rate_store=` accepts any `ActiveSupport::Cache`
+  store responding to `increment`, or `nil` (default) to count through the
+  application's own cache store.
+
+`Hitch::DeviceGrant.mint!(client_id:, scopes:, resource_uri:,
+token_endpoint_auth_method: nil)`,
+`.find_pending_by_user_code(input)`, `.approve!(user_code:, principal:,
+client_name:)`, `.deny!(user_code:)`,
+`.exchange_device_code!(raw_device_code:, client_id:, resource_uri:,
+token_endpoint_auth_method:)`, and
+`.cleanup_expired!` are public and keep their names and arguments within
+0.4.x. `token_endpoint_auth_method` accepts `none` or `client_secret_basic`;
+when omitted at mint, Hitch derives it from the currently registered client.
+Hosts running a cleanup job should add
+`Hitch::DeviceGrant.cleanup_expired!` beside the access-token call.
+
 `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`
 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.
+`hitch:clients:create_confidential`, `hitch:clients:rotate_secret`,
+`Hitch::AccessToken.cleanup_expired!`, and
+`Hitch::DeviceGrant.cleanup_expired!` are public and keep their names and
+arguments within 0.4.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
@@ -302,7 +447,8 @@ resources, caching, subscriptions, or all-server-suite conformance.
 
 The package/client harness is also repository test infrastructure, not
 runtime API. `bin/package-smoke` installs the exact built gem in a disposable
-Rails application and drives the full flow. `bin/package-smoke
+Rails application and drives authorization-code and device tokens through
+the MCP endpoint. `bin/package-smoke
 --automated-clients` adds one ephemeral Redis service, exercising
 `RedisCacheStore` as one supported admission backend, and the exhaustive
 official TypeScript/Python SDK 2.0.0 public/confidential matrix. The
@@ -314,9 +460,7 @@ 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.3.0` is the latest published release. `0.4.0` is prepared and unreleased:
+the version is bumped and this document is current, but no `v0.4.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`](https://github.com/tylerklose/hitch-rails/blob/v0.3.0/docs/public_api/0.3.0.md) — the full compatibility surface
+- README, "Refresh tokens" — rotation, families, reuse detection, and the
+  reasoning behind each default