hitch-rails 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5e84192f904de0068b0a3defad8e24fc016505b374d376574fec4a88a1d6ce4
-  data.tar.gz: dabd5731714cef7be235b377ffd89f831fb7f385d3e31d67395679b751d592de
+  metadata.gz: 5af2b72b1671016730a86c5a05c2a33b0e8f220e8012bbb7e9649ab51cd140ca
+  data.tar.gz: 71d72c4733f0e2cfc0eabbfbe87ea72603b6056d2b9bd2cf1ec15d24714c1f32
 SHA512:
-  metadata.gz: d114e3882f4ba5beb1a7bf467c9f66da01db784989e9c1b8d6efd3d0b7dda97871ff2959ba31a899cc12222a324150c6531394027a136ee1cd9342f3cbb7b210
-  data.tar.gz: 49aa9b3fe6450c1182768757878f76cc5ed380725a3e017384560a03fb855db1c8035a370b4157c581222a67635156e9da744782eba25f46bdfb21811623acd4
+  metadata.gz: 4403699378b070073e227fe7e8227c9a9ca543ddb8d6f9459cf76fbaaf6d71814c325f6c2f04d37227bdb4ab3770e5515b2180d705101f7c47c7d9a7a0156a0b
+  data.tar.gz: b28b7b108e3b38fae1e618a3c5c390cdeb16e197ea0d1ede3274be417a9fec19b87c7036f128045aa81c8551b0a4a77db0edb51a7f0186ea342431b140206e8c

data/CHANGELOG.md

@@ -5,6 +5,120 @@ 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).
 
+## [Unreleased]
+
+## [0.5.0] - 2026-09-05
+
+Upgrading from 0.4.0 requires MCP >= 1.4 and a review of native redirect
+schemes and CIMD metadata. No new migrations are required. See
+[`docs/upgrading/0.4-to-0.5.md`](docs/upgrading/0.4-to-0.5.md).
+
+### Added
+
+- **`Hitch::MCP::UntrustedText.wrap(text, source:)`** labels
+  attacker-influenced tool-result text (for example a worker bio) so a
+  model can treat it as data, not instructions. Opt-in: Hitch never wraps
+  unless the tool author calls it. Returns one frozen String for
+  `Result.text` / structured `text:`; it is not a Result. The README
+  points at the client half of the contract.
+- Rails 7.2 is supported again, with a Ruby 3.3/Rack 2.2/PostgreSQL release
+  lane that exercises the full suite, eager loading, and the real Redis
+  fallback gate.
+
+### Fixed
+
+- Registry preparation now runs after eager loading instead of constantizing
+  host tools from Rails' initial `to_prepare` callback. Eager boot and reload
+  remain fail-fast; non-eager applications prepare on first MCP use, and
+  `hitch:doctor` prepares only after the application boots. This removes the
+  early-load warning without serving stale reloadable classes.
+  ([#44](https://github.com/tylerklose/hitch-rails/issues/44))
+
+### Changed
+
+- **Native redirect URIs are an allowlist, vouched — not a denylist.**
+  Grok Bot's `grokbot://mcp/oauth/callback` and Cursor's
+  `cursor://anysphere.cursor-mcp/oauth/callback` need RFC 8252 §7.1
+  private-use schemes (RFC 7591 §2 already carves those out of the
+  HTTPS requirement). Admitting any hierarchical custom scheme let
+  anyone DCR-register `evil://claude.ai/callback`, which consent then
+  branded as Claude. Hitch now 302s only to `https`, RFC 8252 loopback
+  `http`, and a shipped allowlist (`grokbot`, `cursor`; hosts may add
+  schemes). `grokbot` requires a CIMD document on `grok.com` / `x.ai`
+  or an operator-registered client; `cursor` requires `cursor.com` /
+  `cursor.sh` or an operator. Open DCR cannot mint those schemes.
+  Privileged schemes (`javascript`, `intent`, `chrome-extension`,
+  `web+*`, `file`, …) stay refused even if listed in config. Consent
+  applies `client_label` to https (and loopback http) hosts, and to
+  a native CIMD document host — never to an attacker-chosen custom-scheme
+  URI host. PKCE S256 stays mandatory.
+- Raise the official Ruby MCP SDK floor from `mcp >= 1.2, < 2` to
+  `mcp >= 1.4, < 2`. Hitch still does not mount `StreamableHTTPTransport`.
+  `subscriptions/listen` (mcp 1.4.0's `serve_subscriptions_listen`) is
+  refused at `Protocol::METHODS` with JSON-RPC `-32601` and
+  `application/json`, because `Endpoint#hitch_mcp_render_protocol!` cannot
+  hold an SSE stream. `server/discover` continues to advertise
+  `{ tools: {} }` with no `listChanged` or `subscribe` flags.
+
+### Security
+
+- **CIMD trailing-dot hosts are refused without a fetch.** A `client_id` whose host ends in `.` is not a metadata-document reference. Previously the host was stripped for the per-host failure cache, so `https://example.com./…` (TLS/SNI failure) poisoned `example.com` for 60 seconds.
+- **CIMD per-host failure cache is DNS/blocklist only.** TLS failure, timeout after connect, RST, and HTTP errors write a per-URL negative only. draft-02 §5.2 says do not cache errors; the per-URL negative and `fetches_per_minute` remain the amplification guard.
+- **CIMD URLs with `.` or `..` path segments are refused** (draft-ietf-oauth-client-id-metadata-document-02 §3).
+- **CIMD documents must be `application/json` or `application/*+json`.** `text/html` is refused. The `client_id` identity check stays exact.
+- **CIMD `redirect_uris` honour DCR's 255-byte per-URI cap.**
+- **Authorization-code `invalid_grant` uses one public `error_description`.** Wrong client, wrong `redirect_uri`, PKCE failure, expired, and unknown all return the same string (RFC 6819). The code is not consumed on a failed binding check.
+- **Device `/activate` sends `Cache-Control: no-store` and `Referrer-Policy: no-referrer`** on the code-entry, confirm, and done pages.
+
+## [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

@@ -49,9 +49,12 @@ needs:
 - **Generators, a test helper, and a read-only `hitch:doctor`** for
   installing, testing, and diagnosing the integration
 
-SQLite and PostgreSQL are supported, on Ruby >= 3.3 and Rails 8.x. CI tests
-Rails 8.0 and 8.1 on every push; later 8.x releases — including edge Rails —
-install and are expected to work, but are not covered by a lane.
+SQLite and PostgreSQL are supported on Ruby >= 3.3, < 4.1 and Rails >= 7.2,
+< 9. CI tests Rails 7.2/Rack 2.2/PostgreSQL, Rails 8.0/SQLite, and Rails
+8.1/PostgreSQL on every push; later 8.x releases — including edge Rails —
+install and are expected to work, but are not covered by a release lane.
+Hitch requires the official Ruby MCP SDK >= 1.4, < 2.
+
 Host models with integer, UUID, or ULID primary keys all work: access tokens
 store principal IDs losslessly as strings.
 
@@ -184,6 +187,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:
@@ -257,6 +261,27 @@ Results go through the closed `Hitch::MCP::Result` channel — `.text`,
 and are size-capped after serialization. Host exception messages are never
 exposed to clients.
 
+### Untrusted text
+
+Hitch does not wrap tool output for you. When a field is attacker-influenced —
+a worker bio, a customer note, scraped copy — the tool author opts in:
+
+```ruby
+Hitch::MCP::Result.text(
+  Hitch::MCP::UntrustedText.wrap(worker.bio, source: "worker.bio")
+)
+```
+
+`wrap` returns one frozen String (`<untrusted source="worker.bio">...</untrusted>`),
+not a Result. Pass it to `Result.text` (or as structured `text:`) like any other
+string. What you wrap is a product decision; Hitch will not infer it.
+
+Wrapping is only the server half of the contract. The MCP client that talks to
+the model still has to treat fenced text as data, not as commands. Hitch cannot
+set that client's system prompt, and we are not prescribing prompt wording —
+Anthropic's [anatomy of effective commerce agents](https://claude.com/blog/the-anatomy-of-effective-commerce-agents)
+is the published version of that split.
+
 Request admission shares one fixed-window quota per principal/client across
 `server/discover`, `tools/list`, and `tools/call`, counted through your cache
 store with HMAC keys (no raw identifiers, no reset on token rotation).
@@ -303,6 +328,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 +359,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 +503,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
@@ -473,8 +619,10 @@ the library default stays `false` so an upgrade never flips it silently.
 
 Enabling CIMD means `/oauth/authorize` makes outbound HTTPS requests to
 caller-chosen URLs, so each fetch is tightly constrained (https on 443 only,
-no redirects, DNS pinned after a non-public-range check, wall-clock budget,
-streamed size cap) and the volume is bounded by two caps:
+no trailing-dot hosts, no `.`/`..` path segments, no redirects, DNS pinned
+after a non-public-range check, wall-clock budget, streamed size cap, and a
+200 must be `application/json` or `application/*+json`) and the volume is
+bounded by two caps:
 
 ```ruby
 config.client_id_metadata_enabled = true
@@ -496,7 +644,16 @@ bin/rails 'hitch:cimd:check[https://some-client.example/client.json]'
 `POST /oauth/register` is disabled by the generated initializer and discovery
 omits `registration_endpoint`. If you enable it, registration is
 unauthenticated, so it is rate-limited per `request.remote_ip` through your
-cache store and rejects malformed or oversized documents before persistence:
+cache store and rejects malformed or oversized documents before persistence.
+Redirect URIs at DCR must be `https` or RFC 8252 loopback `http`
+(`localhost`, `127.0.0.1`, `::1`). Native private-use schemes are not
+self-registered: Hitch 302s to `grokbot` and `cursor` only when a CIMD
+document host vouches for them (`grok.com` / `x.ai`, `cursor.com` /
+`cursor.sh`) or the client is operator-registered. Hosts may add schemes
+with `config.native_redirect_schemes`; those are operator-only unless
+`config.native_redirect_vouchers` also names a CIMD document host.
+Privileged schemes (`javascript`, `intent`, `chrome-extension`,
+`web+*`, `file`, …) are never addable. Remote `http` is refused.
 
 ```ruby
 config.dynamic_client_registration_enabled = true
@@ -525,10 +682,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
@@ -551,12 +715,20 @@ instance variables: `@client_name`, `@redirect_host`, `@brand_name`,
 `@oauth_params`, `@resource`, and `@scopes` (already clamped to
 `supported_scopes` — show them so consent is informed).
 
-`@client_name` is derived from the verified redirect host through
+`@client_name` is derived from a verified identity through
 `config.client_names`, a Hash of host matchers (exact `String` or `Regexp`)
-to labels, checked in order. The default table labels the common MCP
-clients; extend it with
+to labels, checked in order. For `https` (and loopback `http`) that identity
+is the redirect host; for a native scheme it is the CIMD document host, or
+the scheme itself when the client is operator-registered — never the
+redirect URI's own host (`mcp` in `grokbot://mcp/…`). 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,16 +739,26 @@ 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
-[`docs/removing.md`](docs/removing.md).
+0.5.0 is the current release. The public API may change before v1.0.0.
+The exact 0.5 public surface is documented in
+[`docs/public_api/0.5.0.md`](https://github.com/tylerklose/hitch-rails/blob/v0.5.0/docs/public_api/0.5.0.md).
+For adopter actions, see
+[`docs/upgrading/0.4-to-0.5.md`](docs/upgrading/0.4-to-0.5.md); removal is
+covered in [`docs/removing.md`](docs/removing.md).
 
 ## Contributing
 

data/SECURITY.md

@@ -12,12 +12,13 @@ release; only the latest release line is supported.
 
 | Version | Supported |
 | ------- | --------- |
-| latest 0.2.x release, and `main` | ✅ |
+| `main` | ✅ |
+| latest 0.5.x release | ✅ |
 
-The supported runtime matrix is Ruby `>= 3.3, < 4.1`, Rails `>= 8.0, < 9`,
-and SQLite or PostgreSQL. Reports that reproduce only on an unsupported
-runtime, adapter, or client version may still reveal a real bug, but the
-maintainer will first confirm them on that matrix.
+The supported runtime matrix is Ruby `>= 3.3, < 4.1`, Rails `>= 7.2, < 9`,
+and SQLite or PostgreSQL. Reports that reproduce
+only on an unsupported runtime, adapter, or client version may still reveal a
+real bug, but the maintainer will first confirm them on that matrix.
 
 ## Reporting a vulnerability
 

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/mcp/endpoint.rb

@@ -204,11 +204,14 @@ module Hitch
       end
 
       def hitch_mcp_dispatch!(verified_request)
+        configuration = Hitch.configuration
         scope = hitch_mcp_resolve_scope
         context = hitch_mcp_context(verified_request, scope:)
-        server_info = Hitch.configuration.mcp.server_info
+        server_info = configuration.mcp.server_info
 
-        snapshot = Hitch.configuration.mcp.registry_snapshot!
+        snapshot = configuration.mcp.ensure_registry_prepared!(
+          supported_scopes: configuration.supported_scopes
+        )
         tools = hitch_mcp_tools(verified_request:, context:, snapshot:)
         return if performed?
 

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
@@ -107,7 +100,7 @@ module Hitch
       oauth_error(
         "invalid_client_metadata",
         "registration request body exceeds #{self.class::MAX_REQUEST_BODY_BYTES} bytes",
-        :content_too_large
+        413
       )
       ""
     end

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