hitch-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f3b81a77da70febf67788591e4d55ea20f4f1ea1dbcfd70cc625acd47a737f9
-  data.tar.gz: 503464b494a7b86afef2c5ee0a45228eb9127bda787f9eb066ffc26e6d42e938
+  metadata.gz: 5af2b72b1671016730a86c5a05c2a33b0e8f220e8012bbb7e9649ab51cd140ca
+  data.tar.gz: 71d72c4733f0e2cfc0eabbfbe87ea72603b6056d2b9bd2cf1ec15d24714c1f32
 SHA512:
-  metadata.gz: cf4c3e492585306009172af921bd17926f6a416f26fae21f685c67d6965cabe5e02354f0e401c80b1cf679d392808b0a3e34103713ffe474787cdb06b0d734f0
-  data.tar.gz: 3b41bc38652a29d79a4fcaff55afd8cb06b15b1c415fd078335f8d3baf6d3f4f8fec77257ffa45b13f3c5740b85734e47b35436a12eb65c3b37ad1cd91702e4d
+  metadata.gz: 4403699378b070073e227fe7e8227c9a9ca543ddb8d6f9459cf76fbaaf6d71814c325f6c2f04d37227bdb4ab3770e5515b2180d705101f7c47c7d9a7a0156a0b
+  data.tar.gz: b28b7b108e3b38fae1e618a3c5c390cdeb16e197ea0d1ede3274be417a9fec19b87c7036f128045aa81c8551b0a4a77db0edb51a7f0186ea342431b140206e8c

data/CHANGELOG.md

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

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.
 
@@ -258,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).
@@ -595,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
@@ -618,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
@@ -680,10 +715,13 @@ 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:
@@ -715,10 +753,12 @@ or undermine its guarantees:
 
 ## Status
 
-0.2.0 is the first public release. The public API may change before v1.0.0.
-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).
+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/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/registration_admission.rb

@@ -100,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/uri_validation.rb

@@ -14,11 +14,14 @@ module Hitch
 
     private
 
-    # Authorization redirect URI: https everywhere except loopback
-    # http (which RFC 8252 permits for native apps).
+    # RFC 7591 §2 requires HTTPS except native loopback (RFC 8252 §7.3)
+    # and native private-use URI schemes (RFC 8252 §7.1). Web clients
+    # stay on https. Native schemes are an allowlist (grokbot, cursor,
+    # plus host-added); who may use one is a separate voucher check.
+    # PKCE (already mandatory) is the RFC 8252 answer to custom-scheme
+    # hijacking.
     def valid_redirect_uri?(uri)
       parsed = URI.parse(uri)
-      return false if parsed.hostname.blank?
       return false unless parsed.userinfo.nil? && !userinfo_component_present?(uri)
       # RFC 6749 §3.1.2: the redirection endpoint URI MUST NOT include a
       # fragment component. Enforced because redirect_uri_matches? does
@@ -28,15 +31,38 @@ module Hitch
       # fragment response modes) would read whatever was smuggled there.
       return false unless parsed.fragment.nil?
 
-      case parsed.scheme
-      when "https" then true
-      when "http"  then loopback_host?(parsed.hostname)
-      else false
+      scheme = parsed.scheme.to_s.downcase
+      case scheme
+      when "https" then parsed.hostname.present?
+      when "http"  then parsed.hostname.present? && loopback_host?(parsed.hostname)
+      else native_redirect_uri?(parsed, scheme)
       end
     rescue URI::InvalidURIError
       false
     end
 
+    # DCR is anonymous self-registration. A native scheme 302 is only
+    # honest when a CIMD document host or an operator vouches for it,
+    # so open registration stays https and loopback http.
+    def self_registered_redirect_uri?(uri)
+      return false unless valid_redirect_uri?(uri)
+
+      %w[https http].include?(URI.parse(uri).scheme.to_s.downcase)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # Allowlisted hierarchical custom scheme with a host. Requiring a
+    # host rejects javascript:alert(1); the refused-scheme list catches
+    # javascript://host/path even if a host stuffed it into config.
+    def native_redirect_uri?(parsed, scheme)
+      return false unless scheme.match?(/\A[a-z][a-z0-9+.-]*\z/)
+      return false unless Hitch.configuration.native_redirect_scheme?(scheme)
+      return false unless parsed.opaque.nil?
+
+      parsed.hostname.present?
+    end
+
     def loopback_host?(host)
       Hitch::ResourceUri::LOOPBACK_HOSTS.include?(host)
     end

data/app/controllers/hitch/activations_controller.rb

@@ -35,6 +35,7 @@ module Hitch
       # MissingTemplate 500.
       request.format = :html
       @brand_name = Hitch.configuration.brand_name
+      protect_activation_response
     end
 
     def new
@@ -154,9 +155,20 @@ module Hitch
       true
     end
 
+    def prepare_oauth_form_response!
+      protect_activation_response
+    end
+
+    # RFC 8628: verification_uri_complete carries the user_code in the
+    # query string; the activation pages must not leak it via Referer.
+    def protect_activation_response
+      hitch_no_store!
+      response.headers["Referrer-Policy"] = "no-referrer"
+    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
+        status: 413
     end
   end
 end

data/app/controllers/hitch/authorizations_controller.rb

@@ -108,7 +108,7 @@ module Hitch
       oauth_error(
         "invalid_request",
         "authorization request body exceeds #{MAX_REQUEST_BODY_BYTES} bytes",
-        :content_too_large
+        413
       )
     end
 

data/app/controllers/hitch/device_authorizations_controller.rb

@@ -106,7 +106,7 @@ module Hitch
       oauth_error(
         "invalid_request",
         "device authorization request body exceeds #{MAX_REQUEST_BODY_BYTES} bytes",
-        :content_too_large
+        413
       )
     end
   end

data/app/controllers/hitch/registrations_controller.rb

@@ -24,7 +24,7 @@ module Hitch
       return if performed?
 
       candidate_uris = normalized.fetch(:redirect_uris)
-      invalid = candidate_uris.reject { |uri| valid_redirect_uri?(uri) }
+      invalid = candidate_uris.reject { |uri| self_registered_redirect_uri?(uri) }
       if invalid.any?
         return oauth_error(
           "invalid_redirect_uri",

data/app/controllers/hitch/tokens_controller.rb

@@ -48,7 +48,7 @@ module Hitch
       return oauth_error("invalid_request", "code is required") if oauth[:code].blank?
       return oauth_error("invalid_request", "code_verifier is required") if oauth[:code_verifier].blank?
       unless Hitch::Pkce.valid_verifier?(oauth[:code_verifier])
-        return oauth_error("invalid_grant", "Invalid or expired authorization code")
+        return invalid_authorization_code
       end
       if oauth[:redirect_uri].present? && !valid_redirect_uri?(oauth[:redirect_uri])
         return oauth_error("invalid_request", "redirect_uri is malformed")
@@ -66,9 +66,16 @@ module Hitch
         redirect_uri: oauth[:redirect_uri]
       )
 
-      return oauth_error("invalid_grant", "Invalid or expired authorization code") if result.nil?
+      return invalid_authorization_code if result.nil?
 
       render_token(result)
+    rescue Hitch::AccessToken::OAuthError => e
+      # RFC 6819: distinct invalid_grant descriptions (wrong client,
+      # wrong redirect_uri, PKCE) let an attacker probe a stolen code.
+      # One public string; the oauth error code stays invalid_grant.
+      return invalid_authorization_code if e.oauth_code == "invalid_grant"
+
+      oauth_error(e.oauth_code, e.description)
     end
 
     def refresh_token_grant(oauth)
@@ -147,8 +154,12 @@ module Hitch
       oauth_error(
         "invalid_request",
         "token request body exceeds #{MAX_REQUEST_BODY_BYTES} bytes",
-        :content_too_large
+        413
       )
     end
+
+    def invalid_authorization_code
+      oauth_error("invalid_grant", "Invalid or expired authorization code")
+    end
   end
 end

data/app/models/hitch/authorization_request.rb

@@ -101,14 +101,20 @@ module Hitch
     end
 
     def redirect_host
-      URI.parse(redirect_uri.to_s).host
+      parsed = URI.parse(redirect_uri.to_s)
+      scheme = parsed.scheme.to_s.downcase
+      return parsed.host if scheme == "https" || scheme == "http"
+
+      native_voucher_identity
     rescue URI::InvalidURIError
       nil
     end
 
     # The consent screen's display name. Never the client's declared name —
-    # that is attacker-controllable in both registration schemes — but a
-    # label derived from the verified redirect_uri host.
+    # that is attacker-controllable in both registration schemes. https
+    # (and loopback http) labels come from the verified redirect host;
+    # a native scheme labels the voucher (CIMD document host, or the
+    # scheme itself), never an attacker-chosen URI host like `mcp`.
     def display_client_name
       friendly_client_name || redirect_host || "An application"
     end
@@ -194,15 +200,18 @@ module Hitch
     end
 
     # The client's declared redirect_uris. nil means "no such client"; an
-    # empty array means "a client, but nothing usable to redirect to". The
-    # gem's https-or-loopback policy (RFC 8252) applies to CIMD documents
-    # here — DCR enforces it at registration time, and a metadata document
-    # never passes through registration, so without this filter CIMD would
-    # bypass a check DCR clients face.
+    # empty array means "a client, but nothing usable to redirect to".
+    # Shape (https, loopback http, allowlisted native) and who may use a
+    # native scheme (CIMD voucher or operator) apply here for every
+    # registration scheme — DCR enforces self-registration at mint time,
+    # but a metadata document never passes through registration, and a
+    # row already in the table must not keep a scheme the client is not
+    # vouched for.
     def registered_redirect_uris
-      return client&.redirect_uris unless ClientIdMetadata.reference?(client_id)
+      declared = client&.redirect_uris
+      return declared if declared.nil?
 
-      client&.redirect_uris&.select { |candidate| valid_redirect_uri?(candidate) }
+      declared.select { |candidate| usable_redirect_uri?(candidate) }
     end
 
     def unknown_client_message
@@ -220,6 +229,39 @@ module Hitch
       Hitch::RateLimitStore.actor_for(principal)
     end
 
+    def usable_redirect_uri?(uri)
+      return false unless valid_redirect_uri?(uri)
+
+      parsed = URI.parse(uri)
+      scheme = parsed.scheme.to_s.downcase
+      return true if scheme == "https" || scheme == "http"
+
+      native_redirect_authorized?(scheme)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def native_redirect_authorized?(scheme)
+      return true if client.is_a?(Hitch::Client) && client.operator_registered_confidential_client?
+      return false unless ClientIdMetadata.reference?(client_id)
+
+      Hitch.configuration.vouches_for_native_redirect?(scheme, URI.parse(client_id).hostname)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # CIMD: the document URL host. Operator / DCR: the scheme. Never the
+    # redirect_uri host of a custom scheme — that slot is attacker-chosen.
+    def native_voucher_identity
+      if ClientIdMetadata.reference?(client_id)
+        URI.parse(client_id).hostname
+      else
+        URI.parse(redirect_uri.to_s).scheme
+      end
+    rescue URI::InvalidURIError
+      nil
+    end
+
     def friendly_client_name
       Hitch.configuration.client_label(redirect_host)
     end

data/app/models/hitch/client_id_metadata/cache.rb

@@ -26,9 +26,9 @@ module Hitch
         "hitch/cimd/v1/failed-host/#{Digest::SHA256.hexdigest(normalized_host(host))}"
       end
 
-      # "evil.example" and "evil.example." are the same DNS name and the
-      # same destination; without stripping the root label they would be
-      # two cache keys, which is one more outbound fetch than intended.
+      # "evil.example" and "EVIL.example" are the same DNS name. Trailing-dot
+      # hosts are refused at shape time and never reach this key; chomp
+      # remains so a host that still arrives cannot split the key.
       def normalized_host(host)
         host.to_s.downcase.chomp(".")
       end

data/app/models/hitch/client_id_metadata/fetcher.rb

@@ -56,23 +56,24 @@ module Hitch
       MAX_BYTES = 64 * 1024
       MAX_REDIRECT_URIS = 20
 
-      # Nothing at that host answered — may block the host's other
-      # documents. Distinct from a document-level failure (plain nil),
-      # which must not, or one bogus URL would take an entire CIMD-hosting
+      # DNS returned nothing, or every address was blocked. May block the
+      # host's other documents. Distinct from a document-level failure
+      # (plain nil) — TLS, timeout after connect, RST, HTTP error — which
+      # must not, or one TLS-failing URL would take an entire CIMD-hosting
       # domain down for everyone on it.
       HOST_FAILURE = :host_failure
 
       class << self
         # [document, ttl] on success (TTL derived from the document's own
-        # cache headers, clamped by config), nil for an unusable document,
-        # HOST_FAILURE when nothing at the host answered.
+        # cache headers, clamped by config), nil for an unusable document
+        # or a URL-level fetch failure, HOST_FAILURE when DNS returned
+        # nothing or every address was blocked.
         def call(client_id, uri)
           Timeout.timeout(TOTAL_BUDGET) do
             address = safe_address(uri.host)
             return HOST_FAILURE if address.nil?
 
             fetched = fetch(uri, address)
-            return HOST_FAILURE if fetched == HOST_FAILURE
             return nil if fetched.nil?
 
             body, ttl = fetched
@@ -81,7 +82,7 @@ module Hitch
           end
         rescue Timeout::Error => e
           log_rejection(client_id, "#{e.class}: #{e.message}")
-          HOST_FAILURE
+          nil
         rescue JSON::ParserError => e
           log_rejection(client_id, "#{e.class}: #{e.message}")
           nil
@@ -122,10 +123,11 @@ module Hitch
         def fetch(uri, address)
           build_connection(uri, address).start { |http| read_document(http, uri) }
         rescue StandardError => e
-          # Connect refused, TLS failure, socket reset: the host did not
-          # answer, which says nothing about any individual document on it.
+          # TLS failure, RST, connect reset after a vetted address: this
+          # URL failed. That says nothing about a sibling document on the
+          # same host, so it is a per-URL negative, not HOST_FAILURE.
           log_rejection(uri.to_s, "#{e.class}: #{e.message}")
-          HOST_FAILURE
+          nil
         end
 
         def build_connection(uri, address)
@@ -166,9 +168,15 @@ module Hitch
               return log_rejection(uri.to_s, "responded #{response.code}, not 200")
             end
 
+            unless json_media_type?(response)
+              return log_rejection(uri.to_s, "Content-Type #{response.content_type.inspect} is not JSON")
+            end
+
             # An advisory check only — Content-Length is written by the same
             # party as the body, and can simply be omitted under chunked
-            # framing. read_capped is what actually enforces the limit.
+            # framing. read_capped is what actually enforces the limit. This
+            # return must stay inside the block form of #request: without
+            # the block, Net::HTTP buffers the entire body first.
             if response["Content-Length"].to_i > MAX_BYTES
               return log_rejection(uri.to_s, "declared Content-Length above the #{MAX_BYTES}-byte cap")
             end
@@ -180,6 +188,16 @@ module Hitch
           end
         end
 
+        # Media type only — parameters such as charset are ignored.
+        # "application/json" or "application/<AS-defined>+json" —
+        # draft-ietf-oauth-client-id-metadata-document-02 §4. text/html
+        # is refused. The client_id identity check stays exact.
+        def json_media_type?(response)
+          media_type = response.content_type.to_s.downcase
+          media_type == "application/json" ||
+            (media_type.start_with?("application/") && media_type.end_with?("+json"))
+        end
+
         # "SHOULD cache metadata respecting HTTP cache headers" — MCP
         # 2026-07-28, Client Registration.
         #
@@ -243,6 +261,9 @@ module Hitch
           redirect_uris = declared.select { |u| u.is_a?(String) }
           return log_rejection(client_id, "document declares no redirect_uris") if redirect_uris.empty?
           return log_rejection(client_id, "document declares too many redirect_uris") if redirect_uris.size > MAX_REDIRECT_URIS
+          if redirect_uris.any? { |u| u.bytesize > Hitch::Client::MAX_REDIRECT_URI_BYTES }
+            return log_rejection(client_id, "a redirect_uri exceeds the #{Hitch::Client::MAX_REDIRECT_URI_BYTES}-byte cap")
+          end
 
           # "The metadata document MUST include at least the following
           # properties: client_id, client_name, redirect_uris" — MCP