hitch-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f06a693bf0801c38fec53dab3f46b4ce8cc5d0e362d39eafebdfaf9b13d1b1
-  data.tar.gz: 35259384a42618dc255dd3a05c06f71bdaca5e17067eacc6b08a1d7564ab10ae
+  metadata.gz: 9f3b81a77da70febf67788591e4d55ea20f4f1ea1dbcfd70cc625acd47a737f9
+  data.tar.gz: 503464b494a7b86afef2c5ee0a45228eb9127bda787f9eb066ffc26e6d42e938
 SHA512:
-  metadata.gz: '0803444dfe9b103310b55e5d154b1e139d17541506d9297a0b00d0774a070176240a46567cbe5c041ecc6c88fa80753dc48f40d508a2f5deabff81283a0b0fa5'
-  data.tar.gz: 22a5065e45a1ec72fe71a70a6bd24fb5c2c6cfbe6a1cda59e4fd581959899d0442dbded72c46a90752553404eb6f09e1502730bd5e96ceb69ce0c77469481202
+  metadata.gz: cf4c3e492585306009172af921bd17926f6a416f26fae21f685c67d6965cabe5e02354f0e401c80b1cf679d392808b0a3e34103713ffe474787cdb06b0d734f0
+  data.tar.gz: 3b41bc38652a29d79a4fcaff55afd8cb06b15b1c415fd078335f8d3baf6d3f4f8fec77257ffa45b13f3c5740b85734e47b35436a12eb65c3b37ad1cd91702e4d

data/CHANGELOG.md

@@ -5,6 +5,135 @@ 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.4.0] - 2026-08-25
+
+Upgrading from 0.3.0 requires running three new migrations. See
+[`docs/upgrading/0.3-to-0.4.md`](docs/upgrading/0.3-to-0.4.md). The feature
+it carries is **off by default**, so nothing changes until you enable it.
+
+### Added
+
+- **Device Authorization Grant (RFC 8628)** — the headless leg of token
+  acquisition. A client with no browser POSTs
+  `/oauth/device_authorization` and receives a short code like `WDJB-MJHT`
+  plus a verification URL; its human opens `/activate` on any device, signs
+  in the way the host app always signs them in, and approves on a consent
+  screen; the polling client receives an ordinary token via
+  `grant_type=urn:ietf:params:oauth:grant-type:device_code`, with the §3.5
+  responses (`authorization_pending`, `slow_down`, `access_denied`,
+  `expired_token`) along the way. The issued token runs through the same
+  authorization-code exchange as every other grant — revocable,
+  audience-bound, digest-at-rest, refresh token included while that feature
+  is on.
+
+  The grant records the token-endpoint authentication method established at
+  mint and requires the mint endpoint, activation screen, and polling client
+  to agree on it, so a registration race cannot lend the grant another
+  voucher and deleting a confidential client cannot downgrade it to public.
+  Device-code expiry ends pending and approved sessions alike. Database check
+  constraints enforce exclusive decisions, an owner for every approval, and
+  approval before consumption.
+
+  The security posture — a vouched client required to mint (CIMD, or an
+  operator-registered confidential client; self-registered DCR clients are
+  refused even when confidential), code entropy and fail-closed counting, the §5.4 phishing
+  copy, voucher-only branding, no metadata fetches from the unauthenticated
+  mint endpoint — is documented in the README's "Device authorization"
+  section and the reasoning in
+  [ADR 0006](docs/adr/0006-device-authorization-grant.md).
+
+  **Off by default** (`config.device_authorization_enabled`), matching the
+  registration posture: disabled means 404 at the endpoints,
+  `unsupported_grant_type` at the token endpoint, and no advertisement in
+  discovery. New settings: `device_code_lifetime_seconds` (600),
+  `device_authorization_interval_seconds` (5), `device_authorization_limit`
+  (20/60s per IP), `device_code_verification_limit` (10/60s per principal),
+  `device_authorization_rate_store` (defaults to the app's cache store).
+
+  Hosts with a cleanup job add `Hitch::DeviceGrant.cleanup_expired!` beside
+  the access-token call. Design decisions are recorded in
+  [ADR 0006](docs/adr/0006-device-authorization-grant.md).
+
+## [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

@@ -184,6 +184,7 @@ config.mcp.max_request_bytes = 1.megabyte
 config.mcp.max_result_bytes = 1.megabyte
 config.principal_method = :current_user  # method on controllers
 config.login_path = "/session/new"       # where to redirect when unauth'd
+config.device_authorization_enabled = false  # RFC 8628; see Device authorization
 ```
 
 The generated route and controller:
@@ -291,8 +292,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
@@ -301,6 +304,9 @@ The OAuth flow needs a browser: a human signs in and presses Approve. An agent
 running from cron or `claude -p` has neither, so issue it a token from the
 console instead. The operator there is both the resource owner and the client,
 so there is no third party for a consent screen to protect anyone from.
+(When nobody has SSH open, the device flow — see Device authorization,
+below — gets the same agent a token with a tap on a phone instead of a
+console command.)
 
 ```sh
 bin/rails hitch:tokens:issue PRINCIPAL=User:1 OUTPUT_FILE=agent.token
@@ -329,6 +335,240 @@ that database access did not already carry.
 Refresh-token issuance is deliberately not implemented, so an expired agent
 token is reissued the same way.
 
+### Agents as principals
+
+A principal is any persisted record. Nothing requires it to be a person, so an
+agent can hold its own account rather than borrowing someone's:
+
+```sh
+bin/rails hitch:tokens:issue PRINCIPAL=Agent:1 CLIENT_ID=nightly NAME="Nightly report"
+```
+
+Tools then authorize against that principal like any other, so an agent gets
+the policy you write for agents rather than a person's:
+
+```ruby
+def self.available_to?(context)
+  context.principal.is_a?(Agent)
+end
+```
+
+`principal_id` is stored as a string, so an `Agent` may key on an integer,
+a UUID, or a ULID.
+
+Agents arrive through this path rather than the OAuth flow for a structural
+reason, not a missing feature: the consent screen resolves the principal from
+your app's own sign-in (`config.principal_method`, default `:current_user`),
+and an agent has no session for it to read. A browser flow always yields the
+signed-in human. Creating the `Agent` record is your application's business —
+Hitch never creates principals.
+
+## 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.
+
+## Device authorization
+
+The flow your TV uses, for agents with no browser (RFC 8628). **Off by
+default**:
+
+```ruby
+config.device_authorization_enabled = true
+```
+
+Who may ask is deliberately narrow: a device grant needs a client somebody
+real vouches for. Either the internet vouches — a CIMD client like Claude,
+whose `client_id` URL serves its own metadata document — or you do, with a
+client badged once at your console:
+
+```sh
+bin/rails hitch:clients:create_confidential CLIENT_ID=nightly-reporter \
+  NAME="Nightly Reporter" REDIRECT_URI=https://agent.example/callback
+```
+
+A client that only ever vouched for itself through open registration is
+refused at the endpoint, even if DCR issued it a secret: client authentication
+proves continuity, not operator endorsement. That anonymous registration is
+exactly the shape the §5.4 phishing scam mints from.
+
+The grant remembers how the client authenticated when it was minted. An
+operator-registered client must present `client_secret_basic` again when it
+polls, and `/activate` trusts only the matching voucher. Deleting,
+reclassifying, or concurrently registering that client cannot turn the grant
+into a different kind of client.
+
+The agent asks for access and relays what it gets back to its human:
+
+```sh
+curl -s https://your-app.example.com/oauth/device_authorization \
+  -u "$CLIENT_ID:$CLIENT_SECRET" \
+  -d resource=https://your-app.example.com/mcp
+# => { "user_code": "WDJB-MJHT",
+#      "verification_uri": "https://your-app.example.com/activate", ... }
+```
+
+The human opens `/activate` on any device — the link in
+`verification_uri_complete` arrives with the code pre-filled — signs in the
+way your app always signs them in, sees who is asking, and taps Approve.
+The agent, polling `POST /oauth/token` with
+`grant_type=urn:ietf:params:oauth:grant-type:device_code` at the returned
+`interval`, receives an ordinary token: revocable, audience-bound, refresh
+token included while that feature is on. Until then it hears
+`authorization_pending`, or `slow_down` when it polls too eagerly; a deny is
+a hard `access_denied`. Once `expires_in` has elapsed, approved and pending
+device codes both answer `expired_token` and cannot mint a token.
+
+No SSH, no secret pasted into a chat, no browser on the machine that needs
+the token. The human is still the root of trust — they just tap instead of
+running a rake task.
+
+What makes short codes safe to type is stated plainly, because two of these
+are yours to operate:
+
+- **Entropy plus counting.** Codes are 8 characters of Crockford base32
+  (~40 bits, no I/L/O/U; typing `o` for `0` still works), live ten minutes,
+  and every verification attempt is counted per signed-in principal —
+  behind your app's own sign-in. Minting is counted per IP. Both quotas
+  **fail closed**: in production an uncountable store refuses the request,
+  and the boot refuses a store that cannot count across processes
+  (`config.device_authorization_rate_store`, defaulting to your cache
+  store — same rule as everything else here).
+- **The words on the page.** The flow's known abuse (RFC 8628 §5.4) is a
+  stranger sending someone a code to approve — every technical control
+  passes, because the grant is genuine. What stands between that email and
+  a token: the vouching rule above means an anonymous attacker cannot mint
+  an approvable grant at all, the `/activate` page says *only enter a code
+  you asked a device for*, and the screen displays only the voucher's word
+  — a metadata client is branded by its own document host, an operator
+  client by the name you chose at the console (labeled as yours). A
+  self-declared name, or a redirect host nothing is ever delivered to in
+  this flow, never displays. If you override these views, keep these
+  meanings intact.
+
+One caveat on the path: the engine is mounted at your root, and a host
+route named `/activate` declared before the mount silently wins. If your
+app already has one, rename one of them before enabling this.
+
+Tunables, with their defaults: `device_code_lifetime_seconds` (600),
+`device_authorization_interval_seconds` (5), `device_authorization_limit`
+(20 mints per IP per minute), `device_code_verification_limit` (10 attempts
+per principal per minute). Design decisions — the alphabet, the fixed
+server-side interval, the deliberate absence of client-metadata fetches at
+the mint endpoint — are recorded in
+[ADR 0006](docs/adr/0006-device-authorization-grant.md).
+
 ## Operator diagnosis
 
 ```sh
@@ -407,11 +647,30 @@ the provided method with whatever job framework you use:
 class CleanupMCPTokensJob < ApplicationJob
   def perform
     Hitch::AccessToken.cleanup_expired!(revoked_retention_days: 30)
+    Hitch::DeviceGrant.cleanup_expired!
   end
 end
 ```
 
-Idempotent; active tokens are never touched.
+Device grants are simpler: the tokens they issue carry the audit trail, so
+rows go a day past expiry. The day is deliberate — it keeps the answer a
+slow-polling device hears (`expired_token`, or `access_denied` after a
+deny) honest regardless of when this job runs — so expect roughly a day's
+worth of mint volume in `hitch_device_grants`, not ten minutes' worth.
+
+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
 
@@ -427,6 +686,11 @@ to labels, checked in order. The default table labels the common MCP
 clients; extend it with
 `config.client_names = Hitch::Configuration::DEFAULT_CLIENT_NAMES.merge("tool.example" => "My Tool")`.
 
+The device-flow screens override the same way:
+`app/views/hitch/activations/{new,confirm,done}.html.erb`. Their warning
+copy is part of the RFC 8628 §5.4 phishing boundary — reword it in your
+product's voice, but keep its meaning (see Device authorization, above).
+
 ## Adopter security requirements
 
 This gem is an OAuth **authorization server** — configure the host correctly
@@ -437,20 +701,30 @@ or undermine its guarantees:
 - **`config.allowed_hosts` / `config.allowed_origins`** — exact allowlists;
   keep them minimal.
 - **`protect_from_forgery`** — keep CSRF protection active on the consent
-  (`POST /oauth/authorize`) path.
+  (`POST /oauth/authorize`) path. On Rails 8.2 defaults (`load_defaults
+  8.2`), forgery protection verifies the browser's `Sec-Fetch-Site` header
+  instead of the token the consent form renders
+  (`forgery_protection_verification_strategy = :header_only`). Browsers
+  send that header automatically, so ordinary approvals are unaffected —
+  but a non-browser agent driving the consent form over HTTPS without it
+  gets a 422 on Approve, token or no token. That is Rails' verification,
+  not a Hitch bug; the strategy is host-owned Rails config
+  (`:header_or_legacy_token` restores the token fallback).
 - **`config.action_dispatch.trusted_proxies`** — set correctly behind a
   reverse proxy so `remote_ip` and scheme are interpreted correctly.
 
 ## Status
 
 0.2.0 is the first public release. The public API may change before v1.0.0.
-The exact public surface is documented in
-[`docs/public_api/0.2.0.md`](docs/public_api/0.2.0.md); removal is covered in
+The exact 0.2 public surface is documented in
+[`docs/public_api/0.2.0.md`](https://github.com/tylerklose/hitch-rails/blob/v0.2.0/docs/public_api/0.2.0.md); removal is covered in
 [`docs/removing.md`](docs/removing.md).
 
 ## 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/concerns/hitch/client_resolution.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Client authentication for the endpoints a machine calls with its own
+  # credentials (RFC 6749 §3.2.1): one resolver and one error mapping,
+  # with each endpoint naming the challenge realm it answers under.
+  module ClientResolution
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from Hitch::ClientAuthentication::Invalid do |error|
+        if error.http_status == :unauthorized
+          response.headers["WWW-Authenticate"] = %(Basic realm="#{client_authentication_realm}")
+        end
+        oauth_error(error.oauth_code, error.message, error.http_status)
+      end
+    end
+
+    private
+
+    def resolved_client_id(oauth)
+      resolved_client_authentication(oauth).client_id
+    end
+
+    def resolved_client_authentication(oauth)
+      Hitch::ClientAuthentication.resolve(
+        request: request,
+        body_client_id: oauth[:client_id],
+        body_secret_present: oauth[:client_secret].present?
+      )
+    end
+  end
+end

data/app/controllers/concerns/hitch/device_authorization_gate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hitch
+  # The device flow's feature gate, stated once: while the flag is off its
+  # endpoints answer bare 404s — the registration posture. POSTs are refused
+  # in admission via OauthFormAdmission's hook, before the body is read, so
+  # no body-cap error names the feature; a GET calls the same method at the
+  # top of its action. (The shared preflight and host checks still answer,
+  # as they do for disabled registration — full indistinguishability is not
+  # claimed.)
+  module DeviceAuthorizationGate
+    private
+
+    def admit_oauth_endpoint!
+      return true if Hitch.configuration.device_authorization_enabled
+
+      head :not_found
+      false
+    end
+  end
+end

data/app/controllers/concerns/hitch/oauth_form_admission.rb

@@ -38,6 +38,7 @@ module Hitch
         require_allowed_hitch_host!
         return false
       end
+      return false unless admit_oauth_endpoint!
 
       raw_body = bounded_oauth_form_body
       return false if performed?
@@ -77,6 +78,15 @@ module Hitch
       false
     end
 
+    # Hook for endpoints that exist only behind a feature flag. Refusing
+    # here answers before the body is read, so no endpoint-specific
+    # body-cap error names a disabled feature. (The shared preflight and
+    # host checks still answer for a disabled endpoint the way they do for
+    # disabled registration — full indistinguishability is not claimed.)
+    def admit_oauth_endpoint!
+      true
+    end
+
     def prepare_oauth_form_response!
     end
   end

data/app/controllers/concerns/hitch/registration_admission.rb

@@ -33,8 +33,7 @@ module Hitch
     end
 
     def admit_registration_request!
-      response.headers["Cache-Control"] = "no-store"
-      response.headers["Pragma"] = "no-cache"
+      hitch_no_store!
 
       # Error rendering and host callbacks can consult `params`. Install an
       # empty body-parameter cache before either can accidentally invoke Rails'
@@ -89,15 +88,9 @@ module Hitch
     end
 
     def admit_registration_rate!
-      Hitch::DynamicRegistrationRateLimit.check!(remote_ip: request.remote_ip)
-      true
-    rescue Hitch::DynamicRegistrationRateLimit::Exceeded => error
-      response.headers["Retry-After"] = error.retry_after.to_s
-      oauth_error("temporarily_unavailable", "Registration rate limit exceeded", :too_many_requests)
-      false
-    rescue Hitch::DynamicRegistrationRateLimit::Unavailable
-      oauth_error("temporarily_unavailable", "Registration is temporarily unavailable", :service_unavailable)
-      false
+      hitch_admit_rate!("Registration") do
+        Hitch::DynamicRegistrationRateLimit.check!(remote_ip: request.remote_ip)
+      end
     end
 
     def bounded_registration_body

data/app/controllers/concerns/hitch/request_admission.rb

@@ -42,5 +42,27 @@ module Hitch
     def finalize_hitch_admission_rejection!
       set_cors_headers if respond_to?(:set_cors_headers, true)
     end
+
+    # RFC 6749 §5.1: responses carrying credentials are never cacheable.
+    # Pragma for the HTTP/1.0 caches still out there.
+    def hitch_no_store!
+      response.headers["Cache-Control"] = "no-store"
+      response.headers["Pragma"] = "no-cache"
+    end
+
+    # One JSON mapping for a fixed-window refusal, shared by every counted
+    # machine endpoint: 429 with Retry-After when counted out, 503 when the
+    # store cannot count. Yields to the limiter; returns whether to proceed.
+    def hitch_admit_rate!(activity)
+      yield
+      true
+    rescue Hitch::RateLimitStore::Exceeded => error
+      response.headers["Retry-After"] = error.retry_after.to_s
+      oauth_error("temporarily_unavailable", "#{activity} rate limit exceeded", :too_many_requests)
+      false
+    rescue Hitch::RateLimitStore::Unavailable
+      oauth_error("temporarily_unavailable", "#{activity} is temporarily unavailable", :service_unavailable)
+      false
+    end
   end
 end

data/app/controllers/concerns/hitch/uri_validation.rb

@@ -41,6 +41,16 @@ module Hitch
       Hitch::ResourceUri::LOOPBACK_HOSTS.include?(host)
     end
 
+    # One answer to "does this URI point at the user's own machine" — both
+    # consent surfaces ask it for their own-computer warning. hostname, not
+    # host: URI#host keeps IPv6 brackets, so "[::1]" would never match.
+    def loopback_http_uri?(candidate)
+      parsed = URI.parse(candidate)
+      parsed.scheme == "http" && loopback_host?(parsed.hostname)
+    rescue URI::InvalidURIError
+      false
+    end
+
     def userinfo_component_present?(value)
       Hitch::ResourceUri.userinfo_component_present?(value)
     end