hitch-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5e84192f904de0068b0a3defad8e24fc016505b374d376574fec4a88a1d6ce4
-  data.tar.gz: dabd5731714cef7be235b377ffd89f831fb7f385d3e31d67395679b751d592de
+  metadata.gz: 9f3b81a77da70febf67788591e4d55ea20f4f1ea1dbcfd70cc625acd47a737f9
+  data.tar.gz: 503464b494a7b86afef2c5ee0a45228eb9127bda787f9eb066ffc26e6d42e938
 SHA512:
-  metadata.gz: d114e3882f4ba5beb1a7bf467c9f66da01db784989e9c1b8d6efd3d0b7dda97871ff2959ba31a899cc12222a324150c6531394027a136ee1cd9342f3cbb7b210
-  data.tar.gz: 49aa9b3fe6450c1182768757878f76cc5ed380725a3e017384560a03fb855db1c8035a370b4157c581222a67635156e9da744782eba25f46bdfb21811623acd4
+  metadata.gz: cf4c3e492585306009172af921bd17926f6a416f26fae21f685c67d6965cabe5e02354f0e401c80b1cf679d392808b0a3e34103713ffe474787cdb06b0d734f0
+  data.tar.gz: 3b41bc38652a29d79a4fcaff55afd8cb06b15b1c415fd078335f8d3baf6d3f4f8fec77257ffa45b13f3c5740b85734e47b35436a12eb65c3b37ad1cd91702e4d

data/CHANGELOG.md

@@ -5,6 +5,55 @@ 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

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:
@@ -303,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
@@ -331,6 +335,34 @@ 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.
@@ -447,6 +479,96 @@ 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
@@ -525,10 +647,17 @@ 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
 ```
 
+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
@@ -557,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
@@ -567,15 +701,23 @@ 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

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

data/app/controllers/hitch/activations_controller.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Hitch
+  # GET /activate  — enter a device code (RFC 8628 §3.3)
+  # POST /activate — verify the code, then approve or deny
+  #
+  # The one browser piece of the device flow. Session-authenticated through
+  # the host's ApplicationController like the consent screen: the host's
+  # sign-in gates it, and current_principal is who the approval binds.
+  #
+  # The page's words are part of the security boundary (§5.4): the flow is
+  # "a stranger asks you to approve a code", so the screen says plainly that
+  # a code should only be entered by the person who asked a device for it,
+  # and a ?user_code= prefill only fills the field — approving always takes
+  # the person's own submit.
+  class ActivationsController < Hitch::ApplicationController
+    include Hitch::OauthFormAdmission
+    include Hitch::DeviceAuthorizationGate
+
+    # Same declaration and reasoning as the consent POST: state-changing,
+    # session-authenticated, so it must not depend on the host having
+    # forgery protection enabled. Guarded for API-only host bases.
+    protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
+
+    # This is a page a person is looking at: every malformed input — a
+    # blank code, a doctored decision — answers with the form and a plain
+    # sentence, never the JSON dialect the inherited rescue speaks.
+    rescue_from Hitch::OauthRequestParameters::Invalid do
+      render_new alert: "Enter the code your device is showing."
+    end
+
+    before_action do
+      # A page for a person, in exactly one dialect: a .json path or a
+      # JSON Accept header must render the HTML answer, not a
+      # MissingTemplate 500.
+      request.format = :html
+      @brand_name = Hitch.configuration.brand_name
+    end
+
+    def new
+      return unless admit_oauth_endpoint!
+      return require_principal! unless current_principal
+
+      # Prefill from verification_uri_complete. Display only — §5.4 wants
+      # the person to see the code and confirm it matches their device, so
+      # a prefilled form still submits by hand.
+      @user_code = DeviceGrant.display_user_code(params[:user_code])
+    end
+
+    def create
+      return require_principal! unless current_principal
+
+      oauth = oauth_parameters(:user_code, :decision, form_only: true)
+      # Absent field, same answer as a blank one — and before the quota:
+      # neither is a guess.
+      return render_new(alert: "Enter the code your device is showing.") if oauth[:user_code].blank?
+      return unless admit_verification_rate!
+
+      grant = DeviceGrant.find_pending_by_user_code(oauth[:user_code])
+      return unknown_code unless grant
+
+      case oauth[:decision]
+      when nil then confirm(grant, oauth[:user_code])
+      when "approve" then approve(grant, oauth[:user_code])
+      when "deny" then deny(oauth[:user_code])
+      else
+        render_new alert: "Something went wrong with that submission. Enter the code again."
+      end
+    end
+
+    private
+
+    # A signed-out visitor following verification_uri_complete must not
+    # leave the live user code sitting in the host's session store for the
+    # code's whole life. They retype it after signing in — it is on the
+    # device screen in front of them, which §5.4 wants them checking
+    # anyway; a signed-in visitor keeps the prefill.
+    def return_to_after_authenticating_url
+      request.base_url + request.path
+    end
+
+    # Verification is the brute-force surface RFC 8628 §5.1 rate-limits, and
+    # the decision POST carries the code too, so every branch of create sits
+    # behind this. Checked per signed-in principal, after authentication —
+    # anonymous traffic cannot drain a person's budget — and after parsing:
+    # a blank or malformed submission is not a guess and spends none either.
+    # Not hitch_admit_rate!: this refusal is a page for a person, not an
+    # OAuth error body.
+    def admit_verification_rate!
+      Hitch::DeviceAuthorizationRateLimit.check_verification!(principal: current_principal)
+      true
+    rescue Hitch::RateLimitStore::Exceeded => error
+      response.headers["Retry-After"] = error.retry_after.to_s
+      render_new alert: "Too many attempts. Wait a minute and try again.", status: :too_many_requests
+      false
+    rescue Hitch::RateLimitStore::Unavailable
+      render_new alert: "Code entry is temporarily unavailable. Try again shortly.",
+        status: :service_unavailable
+      false
+    end
+
+    def confirm(grant, user_code, activation: nil)
+      @activation = activation || DeviceActivation.new(grant, principal: current_principal)
+      @user_code = DeviceGrant.display_user_code(user_code)
+      render :confirm
+    end
+
+    def approve(grant, user_code)
+      activation = DeviceActivation.new(grant, principal: current_principal)
+      # No Approve for a client that cannot be verified right now. The
+      # grant is live and pending, so answer with the honest confirm
+      # screen — "used or expired" would be false, and the failure may be
+      # transient (a rate-limited or momentarily unreachable document).
+      # The same activation is threaded through, so the screen shows the
+      # state this decision was refused on.
+      return confirm(grant, user_code, activation: activation) if activation.unverified?
+
+      decided = DeviceGrant.approve!(
+        user_code: user_code,
+        principal: current_principal,
+        client_name: activation.audit_client_name
+      )
+      return unknown_code unless decided
+
+      @decision = :approved
+      render :done
+    end
+
+    def deny(user_code)
+      return unknown_code unless DeviceGrant.deny!(user_code: user_code)
+
+      @decision = :denied
+      render :done
+    end
+
+    # One message for never-existed, expired, and already-decided alike: a
+    # more specific answer would tell a guesser which codes are live.
+    def unknown_code
+      render_new alert: "That code isn't waiting for approval. " \
+        "It may have expired or already been used — ask your device for a fresh one."
+    end
+
+    # Assigns everything the template needs itself: some callers run from
+    # admission, before the before_action.
+    def render_new(alert:, status: :unprocessable_entity)
+      request.format = :html
+      @alert = alert
+      @user_code = nil
+      @brand_name = Hitch.configuration.brand_name
+      render :new, status: status
+    end
+
+    def preserve_oauth_authenticity_token?
+      true
+    end
+
+    def reject_oversized_oauth_form_body!
+      render_new alert: "That submission was too large. Enter just the short code your device is showing.",
+        status: :content_too_large
+    end
+  end
+end

data/app/controllers/hitch/application_controller.rb

@@ -55,5 +55,35 @@ module Hitch
 
       nil
     end
+
+    private
+
+    def require_principal!
+      # Remember where the user was headed so the host's auth flow returns
+      # them here after login. Rails 8's built-in authentication reads
+      # session[:return_to_after_authenticating] in after_authentication_url;
+      # normally its own require_authentication callback sets this, but
+      # these controllers skip that callback (see above) and redirect to
+      # login_path themselves, so the return location is set here. Harmless
+      # for hosts that never read the key. Only meaningful on a GET render —
+      # a POST without a session isn't a real flow.
+      session[:return_to_after_authenticating] = return_to_after_authenticating_url if request.get?
+
+      path = Hitch.configuration.login_path
+      target = path.respond_to?(:call) ? path.call(request) : path
+
+      if target.present?
+        redirect_to target, allow_other_host: true
+      else
+        render plain: "Authentication required", status: :unauthorized
+      end
+    end
+
+    # What the host's login flow returns the visitor to. The activation
+    # screen overrides this to drop its query string: the prefill link
+    # carries a live user code, and the session store must not keep one.
+    def return_to_after_authenticating_url
+      request.url
+    end
   end
 end

data/app/controllers/hitch/authorizations_controller.rb

@@ -36,8 +36,9 @@ module Hitch
     # protection enabled — an API-only host, or one that disables it
     # app-wide, would otherwise leave Approve forgeable (an attacker
     # auto-approving an authorization in a logged-in victim's session).
-    # The rendered consent form (form_with) carries the token, so
-    # legitimate submits are unaffected. Guarded: an
+    # The rendered consent form (form_with) carries the token, and
+    # browsers send Sec-Fetch-Site — whichever the host's verification
+    # strategy consults, legitimate submits are unaffected. Guarded: an
     # ActionController::API-derived host base doesn't define the macro,
     # and such a host can't serve the HTML consent screen anyway.
     protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
@@ -121,32 +122,9 @@ module Hitch
     # already passed exact registered-URI validation, so construct the 302
     # directly and keep the credential out of redirect instrumentation.
     def redirect_to_client(location)
-      response.headers["Cache-Control"] = "no-store"
-      response.headers["Pragma"] = "no-cache"
+      hitch_no_store!
       response.headers["Location"] = location
       head :found
     end
-
-    def require_principal!
-      # Remember where the user was headed so the host's auth flow returns
-      # them to the consent screen after login. Rails 8's built-in
-      # authentication reads session[:return_to_after_authenticating] in
-      # after_authentication_url; normally its own require_authentication
-      # callback sets this, but the consent controller skips that callback
-      # (see ApplicationController) and redirects to login_path itself, so
-      # we set the return location here. Harmless for hosts that never read
-      # the key. Only meaningful on the GET consent render — a POST without
-      # a session isn't a real flow.
-      session[:return_to_after_authenticating] = request.url if request.get?
-
-      path = Hitch.configuration.login_path
-      target = path.respond_to?(:call) ? path.call(request) : path
-
-      if target.present?
-        redirect_to target, allow_other_host: true
-      else
-        render plain: "Authentication required", status: :unauthorized
-      end
-    end
   end
 end