hitch-rails 0.2.0

data/app/models/hitch/client_id_metadata.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  # Client ID Metadata Documents (CIMD).
+  #
+  # MCP 2026-07-28 deprecates Dynamic Client Registration in favour of
+  # CIMD: instead of pre-registering and receiving an opaque client_id,
+  # a client uses an https URL as its client_id, and the authorization
+  # server fetches the client metadata from that URL.
+  #
+  # That inverts the trust model. DCR data arrives on a request the
+  # server is already handling; CIMD makes the AUTHORIZATION SERVER issue
+  # an outbound request to a URL the caller chose. /oauth/authorize
+  # requires a signed-in principal, so the caller is authenticated rather
+  # than anonymous — a low bar on any host with open sign-up, and note
+  # the GET consent path carries no CSRF token, so a fetch can be driven
+  # from a logged-in victim's browser. Every guard here exists because of
+  # that inversion:
+  #
+  #   - https only, no redirects followed, no userinfo, no fragment
+  #   - DNS resolved once, every address checked against a blocklist of
+  #     non-public ranges, then the connection PINNED to the checked
+  #     address via Net::HTTP#ipaddr= so a second lookup can't return a
+  #     different answer (DNS rebinding)
+  #   - hard caps on time and response size
+  #   - the document's own `client_id` must equal the URL it came from,
+  #     so a document cannot claim to be a different client
+  #   - successes and failures are both cached, so a hostile or dead URL
+  #     cannot be used to make the authorize endpoint issue an outbound
+  #     request per inbound request. Note this one depends on the host
+  #     having a real Rails.cache: under a NullStore (Rails' default in
+  #     test, and in development without tmp/caching-dev.txt) nothing is
+  #     retained between requests and the amplification guard is absent.
+  #
+  # Disabled unless the host opts in (`config.client_id_metadata_enabled`).
+  # The feature adds an outbound-fetch surface to an endpoint that had
+  # none, and DCR still works, so it is not something to switch on for an
+  # adopter who has not considered it.
+  class ClientIdMetadata
+    Document = Struct.new(:client_id, :client_name, :redirect_uris, keyword_init: true)
+
+    # CIMD documents live on ordinary https endpoints. Allowing an
+    # arbitrary port would let a caller drive TLS connections to any
+    # host:port from the authorization server's egress address — the
+    # standard way around a third party's source-IP allowlist.
+    ALLOWED_PORT = 443
+
+    # Process-wide by design: both throttle bounds are this process's share
+    # of outbound work (see Throttle).
+    @throttle = Throttle.new
+
+    # Failure sentinels (see Fetcher and Throttle for the semantics).
+    HOST_FAILURE = Fetcher::HOST_FAILURE
+    # Refused because a cap was already spent — no fetch was attempted, so
+    # nothing is known and nothing may be cached (see Throttle).
+    CAPACITY_EXCEEDED = Throttle::CAPACITY_EXCEEDED
+    # Refused because this principal spent its minute budget. Same rule.
+    RATE_LIMITED = :rate_limited
+
+    # Result of a diagnostic fetch. Separate from Document deliberately:
+    # this is operator-facing and describes an attempt, not a client.
+    Diagnosis = Struct.new(:outcome, :detail, keyword_init: true) do
+      def ok? = outcome == :ok
+    end
+
+    class << self
+      # A client_id is a CIMD reference when it is an https URL. Opaque
+      # DCR client_ids (UUIDs) never match, so the two schemes coexist
+      # without ambiguity.
+      def reference?(client_id)
+        return false unless Hitch.configuration.client_id_metadata_enabled
+
+        document_url?(client_id)
+      end
+
+      # The shape half of reference?, without consulting the enablement
+      # flag. Split out so the operator diagnostic can run BEFORE CIMD is
+      # switched on — which is the only moment its answer is useful.
+      #
+      # "The client_id URL MUST use the 'https' scheme and contain a path
+      # component" — MCP 2026-07-28, Client Registration. A bare origin
+      # is not a metadata document URL, so it falls through to the
+      # opaque/DCR lookup rather than triggering an outbound fetch.
+      def document_url?(client_id)
+        return false if client_id.blank?
+
+        uri = URI.parse(client_id.to_s)
+        uri.is_a?(URI::HTTPS) && uri.host.present? && uri.path.present? && uri.path != "/"
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # Returns a Document, or nil for anything that isn't a usable
+      # client metadata document. Never raises into the authorize flow:
+      # a fetch failure is an untrusted client's problem, not a 500.
+      # `actor` identifies the signed-in principal driving this
+      # resolution, for per-actor rate limiting. Optional: omitted, only
+      # the concurrency cap applies.
+      def resolve(client_id, actor: nil)
+        return nil unless reference?(client_id)
+
+        key = Cache.key(client_id)
+        cached = Cache.read(key)
+
+        unless cached.nil?
+          return nil if cached == false
+
+          document = Cache.rehydrate(cached)
+          return document if document
+
+          # An entry we can't read is treated as a miss rather than
+          # propagating. A Document member added in a later release, a
+          # rolling deploy sharing a cache between two versions, or a
+          # host configuring a coder that stringifies keys would
+          # otherwise turn /oauth/authorize into a 500 for that
+          # client_id until the TTL expired.
+          Cache.delete(key)
+        end
+
+        # Shape is judged BEFORE either cap is touched. Rejecting a URL on
+        # its scheme, port, userinfo or fragment costs nothing outbound,
+        # so charging it would let a caller spend their own minute budget
+        # on requests that never sent a packet — and then be refused a
+        # legitimate fetch. Shape rejects are never cached, either:
+        # repeating the check is free, while writing an entry per
+        # malformed client_id lets a caller fill a shared cache —
+        # evicting the host app's own entries — without sending a single
+        # packet.
+        target = fetch_target(client_id)
+        return nil if target.nil?
+
+        # A host that just failed to answer at all is not retried,
+        # whatever path or query is hung off it. Keyed by URL alone the
+        # negative cache is defeated by appending ?n=1, ?n=2 — each a
+        # distinct key and each a valid CIMD reference.
+        host = target.host
+        return nil if Cache.read(Cache.failure_key(host)) == false
+
+        # Both caps are consulted only on a genuine miss. A cached
+        # resolution costs nothing outbound, so charging it against
+        # either budget would penalise the common case and make a busy,
+        # correctly-configured server throttle itself.
+        #
+        # Capacity is taken FIRST, and the minute budget is only charged
+        # once a slot is held. The other order spends a token on a
+        # request that never sent a packet — which turns a squeeze on the
+        # slots into a way to drain every victim's own budget while they
+        # retry, locking them out past the point where the slots free up.
+        outcome = with_fetch_capacity do
+          charge_rate_limit(actor) ? Fetcher.call(client_id, target) : RATE_LIMITED
+        end
+
+        case outcome
+        when CAPACITY_EXCEEDED, RATE_LIMITED
+          # Deliberately no cache write of any kind — see the constants.
+          nil
+        when Array
+          # [document, ttl] — the TTL is derived from the document's own
+          # HTTP cache headers, clamped by config.
+          document, ttl = outcome
+          Cache.write(key, document.to_h, ttl) if ttl.positive?
+          document
+        when HOST_FAILURE
+          Cache.write(key, false, Cache::FAILURE_TTL)
+          Cache.write(Cache.failure_key(host), false, Cache::FAILURE_TTL)
+          nil
+        else
+          # A document-level failure — 404, malformed JSON, a document
+          # naming the wrong client_id. It says nothing about its
+          # neighbours, so it must NOT block them: one domain hosting
+          # many client documents is the normal CIMD deployment shape,
+          # and poisoning the host on a per-document failure would let
+          # anyone hold that whole domain offline by requesting a single
+          # bogus URL on it once a minute.
+          Cache.write(key, false, Cache::FAILURE_TTL)
+          nil
+        end
+      end
+
+      # Number of fetches in flight right now. Test seam.
+      def fetches_in_flight
+        @throttle.in_flight
+      end
+
+      # Operator-facing check that this host can actually reach and parse a
+      # client metadata document, for confirming egress before enabling
+      # CIMD. Takes a URL the operator already trusts.
+      #
+      # Reports only. Whether one document is reachable right now is a
+      # different question from whether this server supports CIMD, and
+      # only the second belongs in the discovery document: a capability
+      # that moved with network conditions would be stale for up to the
+      # discovery cache lifetime, and would tell clients nothing they
+      # could act on.
+      #
+      # Skips the caches and the per-principal limit (there is no
+      # principal) but not the SSRF constraints or the concurrency cap —
+      # exercising the real fetch path is the entire point.
+      def diagnose(client_id)
+        # Deliberately ignores client_id_metadata_enabled. The whole point
+        # is to answer "can this host reach a document?" BEFORE deciding
+        # to turn CIMD on, so gating the probe on the setting it informs
+        # makes it useless exactly when it is needed. That flag governs
+        # discovery and real authorization traffic; it does not govern an
+        # operator running a command.
+        unless document_url?(client_id)
+          return Diagnosis.new(outcome: :not_a_reference,
+                               detail: "not an https URL with a path component, so it would be treated as an opaque client_id")
+        end
+
+        target = fetch_target(client_id)
+        if target.nil?
+          return Diagnosis.new(outcome: :rejected_shape,
+                               detail: "must be https on port #{ALLOWED_PORT}, with no userinfo and no fragment")
+        end
+
+        case (outcome = with_fetch_capacity { Fetcher.call(client_id, target) })
+        when Array
+          Diagnosis.new(outcome: :ok, detail: "resolved #{outcome.first.redirect_uris.length} redirect_uri(s)")
+        when CAPACITY_EXCEEDED
+          Diagnosis.new(outcome: :no_capacity, detail: "every fetch slot is currently busy")
+        when HOST_FAILURE
+          Diagnosis.new(outcome: :unreachable,
+                        detail: "DNS, connect, TLS or timeout failed — check direct egress on port #{ALLOWED_PORT}; " \
+                                "an ambient http_proxy is deliberately ignored")
+        else
+          Diagnosis.new(outcome: :invalid_document,
+                        detail: "the host answered but the document was unusable — the log line for this URL says why")
+        end
+      end
+
+      private
+
+      # The limit is read from config at acquisition time — a host may
+      # change it, and tests do.
+      def with_fetch_capacity(&block)
+        @throttle.with_capacity(integer_setting(:client_id_metadata_max_concurrent_fetches), &block)
+      end
+
+      def charge_rate_limit(actor)
+        limit = integer_setting(:client_id_metadata_fetches_per_minute)
+        # nil disables. 0 and below block, matching the concurrency knob —
+        # the most restrictive-looking setting must not be the one that
+        # removes the protection.
+        return true if limit.nil?
+        return false if limit <= 0
+
+        if actor.blank?
+          # Not reachable from the shipped controller — both authorize
+          # actions bail to require_principal! first — but a host whose
+          # principal_method returns something without #id (a claims
+          # hash, a bare identifier) would land here and silently get no
+          # rate limiting at all.
+          warn_once(:cimd_rate_limit_no_actor,
+                    "client_id_metadata_fetches_per_minute is set but the resolution had no actor; " \
+                    "per-principal rate limiting is not being applied")
+          return true
+        end
+
+        @throttle.charge(actor, limit: limit)
+      end
+
+      # Test seam: current count for an actor in this minute.
+      def fetches_charged_to(actor)
+        @throttle.charged_to(actor)
+      end
+
+      # Reads a numeric setting without trusting its type. The docs say
+      # "nil disables", and the obvious wrong guess at that is `false` —
+      # whose #to_i does not exist, which would raise NoMethodError
+      # straight out of resolve and 500 /oauth/authorize on the
+      # default-on path. Anything not coercible to an Integer is treated
+      # as unset rather than fatal.
+      def integer_setting(name)
+        case (value = Hitch.configuration.public_send(name))
+        when Integer then value
+        # Strings are accepted because settings often arrive from ENV.
+        # Floats are NOT: Kernel.Integer(2.5) truncates to 2, which would
+        # silently honour a value the docs say is unset.
+        when String then Integer(value, exception: false)
+        end
+      end
+
+      # Warns once per process per reason. These describe a standing
+      # misconfiguration, not a per-request event; logging them on every
+      # authorize would bury the thing it is warning about.
+      def warn_once(reason, message)
+        @warned ||= {}
+        return if @warned[reason]
+
+        @warned[reason] = true
+        Rails.logger&.warn("[hitch] #{message}")
+      rescue StandardError
+        nil
+      end
+
+      # Parses a client_id into the URI to fetch, or nil when its shape
+      # rules it out. Deliberately separate from the Fetcher call and
+      # called before the caps: none of these checks costs a packet, so
+      # none of them should cost a token.
+      def fetch_target(client_id)
+        uri = URI.parse(client_id)
+        return nil if uri.userinfo.present? || uri.fragment.present?
+        return nil unless uri.port == ALLOWED_PORT
+
+        uri
+      rescue URI::InvalidURIError
+        # Unreachable in practice: both callers gate on document_url?,
+        # which already parsed this exact string.
+        nil
+      end
+    end
+  end
+end

data/app/models/hitch/client_redirect_uri.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hitch
+  class ClientRedirectUri < ApplicationRecord
+    self.table_name = "hitch_client_redirect_uris"
+
+    belongs_to :client,
+      class_name: "Hitch::Client",
+      foreign_key: :hitch_client_id,
+      inverse_of: :redirect_uri_records
+
+    validates :uri, presence: true, uniqueness: { scope: :hitch_client_id }
+  end
+end

data/app/models/hitch/mcp/context.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    # Frozen, request-local authority envelope passed to host MCP policy and
+    # behavior. Host and Active Record references are intentionally preserved
+    # as opaque references; freezing this envelope does not claim to freeze
+    # those objects.
+    class Context
+      attr_reader :principal, :access_token, :scope, :granted_scopes, :client_id,
+        :resource, :request_id, :remote_ip, :user_agent, :protocol_version, :meta
+
+      def initialize(
+        principal:,
+        access_token:,
+        scope:,
+        granted_scopes:,
+        client_id:,
+        resource:,
+        request_id:,
+        remote_ip:,
+        user_agent:,
+        protocol_version:,
+        meta:
+      )
+        raise ArgumentError, "principal is required" if principal.nil?
+        raise ArgumentError, "access_token is required" if access_token.nil?
+
+        @principal = principal
+        @access_token = access_token
+        @scope = scope
+        @granted_scopes = copy_scopes(granted_scopes)
+        @client_id = copy_required_string(client_id, "client_id")
+        @resource = copy_required_string(resource, "resource")
+        @request_id = copy_request_id(request_id)
+        @remote_ip = copy_required_string(remote_ip, "remote_ip")
+        @user_agent = copy_optional_string(user_agent, "user_agent")
+        @protocol_version = copy_required_string(protocol_version, "protocol_version")
+        @meta = copy_meta(meta)
+        freeze
+      end
+
+      private
+
+      def copy_scopes(values)
+        raise ArgumentError, "granted_scopes must be an Array" unless values.is_a?(Array)
+
+        values.map do |value|
+          copy_required_string(value, "granted_scopes entries")
+        end.freeze
+      end
+
+      def copy_request_id(value)
+        unless value.is_a?(String) || value.is_a?(Numeric)
+          raise ArgumentError, "request_id must be a String or Numeric"
+        end
+
+        value.is_a?(String) ? value.dup.freeze : value
+      end
+
+      def copy_required_string(value, name)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, "#{name} must be a nonempty String"
+        end
+
+        value.dup.freeze
+      end
+
+      def copy_optional_string(value, name)
+        return if value.nil?
+
+        raise ArgumentError, "#{name} must be a String or nil" unless value.is_a?(String)
+
+        value.dup.freeze
+      end
+
+      def copy_meta(value)
+        raise ArgumentError, "meta must be a Hash" unless value.is_a?(Hash)
+
+        Internal::JsonValues.copy(
+          value,
+          keys: :string, symbols: :reject, foreign: :reject, freeze: true,
+          on_invalid: lambda do |reason, _detail|
+            raise ArgumentError,
+              (reason == :key ? "meta keys must be Strings" : "meta must contain only JSON values")
+          end
+        )
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/forbidden.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    # Raised by host argument policy to deny one otherwise admissible tool call.
+    # Its message is always private and never crosses the MCP boundary.
+    class Forbidden < StandardError
+    end
+  end
+end

data/app/models/hitch/mcp/internal/bearer_challenge.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  module MCP
+    module Internal
+      # Bearer token extraction and the WWW-Authenticate challenges the
+      # endpoint issues (RFC 6750 §3, RFC 9728 protected-resource metadata).
+      module BearerChallenge
+        MAX_BEARER_TOKEN_BYTES = 512
+
+        module_function
+
+        def token(authorization)
+          authorization = authorization.to_s
+          return if authorization.bytesize > MAX_BEARER_TOKEN_BYTES + 7
+          return unless authorization.valid_encoding?
+          return if authorization.match?(/[\u0000-\u001F\u007F-\u009F]/)
+
+          match = authorization.match(/\ABearer ([A-Za-z0-9_-]{1,#{MAX_BEARER_TOKEN_BYTES}})\z/i)
+          match && match[1]
+        end
+
+        # A generic 401 starts the least-privilege authorization flow with the
+        # host's base/default scope. Protected-resource metadata still
+        # advertises the complete supported set, and a known available tool
+        # names its complete static requirement in a later 403 step-up.
+        def challenge
+          scope = Hitch.configuration.supported_scopes.first
+          %(Bearer resource_metadata="#{resource_metadata_url}", scope="#{scope}")
+        end
+
+        def insufficient_scope(required_scopes)
+          "Bearer error=\"insufficient_scope\", " \
+            "scope=\"#{required_scopes.join(' ')}\", " \
+            "resource_metadata=\"#{resource_metadata_url}\""
+        end
+
+        # Derived from the canonical resource_uri, not handed in: the issuer
+        # inside a challenge must be the same bytes discovery advertises, and
+        # the one derivation is what guarantees it (INV-MCP-024).
+        def resource_metadata_url
+          Hitch::ResourceUri.protected_resource_metadata_url(
+            URI.parse(Hitch.configuration.resource_uri.to_s)
+          )
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/cors_policy.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # CORS decisions for the endpoint: an exact origin allowlist (plus
+      # loopback in development and test), and a fixed preflight contract —
+      # POST only, a closed request-header set.
+      module CorsPolicy
+        ALLOWED_REQUEST_HEADERS = %w[
+          Content-Type
+          Authorization
+          MCP-Protocol-Version
+          Mcp-Method
+          Mcp-Name
+        ].freeze
+        LOOPBACK_ORIGIN = %r{\Ahttps?://(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?\z}
+        PREFLIGHT_RESPONSE_HEADERS = {
+          "Access-Control-Allow-Methods" => "POST",
+          "Access-Control-Allow-Headers" => ALLOWED_REQUEST_HEADERS.join(", "),
+          "Access-Control-Max-Age" => "600"
+        }.freeze
+
+        module_function
+
+        def origin_allowed?(origin)
+          return false unless origin.is_a?(String) && origin.valid_encoding?
+          return false if origin.empty? || origin.include?(",") || HeaderField::CONTROLS.match?(origin)
+          return true if Hitch.configuration.allowed_origins.include?(origin)
+
+          Rails.env.local? && LOOPBACK_ORIGIN.match?(origin)
+        end
+
+        def preflight_allowed?(requested_method:, requested_headers:)
+          method = HeaderField.single(requested_method)
+          headers = requested_header_list(requested_headers)
+          return false unless method == "POST" && headers
+
+          allowed = ALLOWED_REQUEST_HEADERS.map(&:downcase)
+          headers.all? { |header| allowed.include?(header.downcase) }
+        end
+
+        def requested_header_list(value)
+          return [] if value.nil? || value.empty?
+          return unless value.is_a?(String) && value.valid_encoding? && !HeaderField::CONTROLS.match?(value)
+
+          values = value.split(",", -1).map { |entry| HeaderField.trim_ows(entry) }
+          values unless values.any? { |entry| entry.nil? || entry.empty? }
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/endpoint_error_reporter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # Reports an endpoint failure without ever accepting the original
+      # exception. Authentication inputs, request bodies, and host state
+      # therefore cannot cross this reporting boundary by accident.
+      class EndpointErrorReporter
+        SOURCE = "hitch.mcp.endpoint"
+        CATEGORIES = {
+          authentication: "authentication",
+          request_admission: "request_admission",
+          dispatch: "dispatch"
+        }.freeze
+
+        class << self
+          def report(category:)
+            SanitizedReport.emit(
+              source: SOURCE,
+              message: "Hitch MCP endpoint failed",
+              context: reporting_context(category)
+            )
+          rescue StandardError, SystemStackError
+            nil
+          end
+
+          private
+
+          def reporting_context(category)
+            context = { hitch_mcp_category: CATEGORIES.fetch(category) }
+            request_id = Observation.current_request_id
+            context[:hitch_mcp_request_id] = request_id.dup.freeze if request_id
+            context.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/error_normalizer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module Hitch
+  module MCP
+    module Internal
+      # Reports only a synthetic failure with fixed structural context, then
+      # returns the same generic tool error for every non-explicit failure.
+      class ErrorNormalizer
+        SOURCE = "hitch.mcp.tool"
+        PHASE_CATEGORIES = {
+          context: "context_handoff",
+          arguments: "argument_normalization",
+          authorization: "argument_policy",
+          execution: "host_execution",
+          result: "result_normalization"
+        }.freeze
+
+        class << self
+          def call(error:, phase:, context:, tool_name:)
+            unless expected_denial?(error, phase)
+              report(error:, phase:, tool_name:)
+              log_local_diagnosis(error:, phase:, tool_name:)
+            end
+            generic_response
+          rescue StandardError, SystemStackError
+            generic_response
+          end
+
+          private
+
+          def expected_denial?(error, phase)
+            phase == :authorization && error.is_a?(Forbidden)
+          end
+
+          def log_local_diagnosis(error:, phase:, tool_name:)
+            category = ResultNormalizer.failure_category(error)
+            LocalDiagnosis.report(
+              "MCP tool #{tool_name.inspect} failed during #{phase}#{" (#{category})" if category}",
+              error
+            )
+          end
+
+          def report(error:, phase:, tool_name:)
+            SanitizedReport.emit(
+              source: SOURCE,
+              message: "Hitch MCP tool execution failed",
+              context: reporting_context(error:, phase:, tool_name:)
+            )
+          end
+
+          def reporting_context(error:, phase:, tool_name:)
+            category = ResultNormalizer.failure_category(error) || PHASE_CATEGORIES.fetch(phase, "tool_boundary")
+            context = { hitch_mcp_category: category.to_s.freeze }
+            if Protocol.tool_name?(tool_name)
+              context[:hitch_mcp_tool] = tool_name.dup.freeze
+            end
+            request_id = Observation.current_request_id
+            context[:hitch_mcp_request_id] = request_id.dup.freeze if request_id
+            context.freeze
+          end
+
+          def generic_response
+            ::MCP::Tool::Response.new(
+              [ { type: "text", text: Protocol::GENERIC_TOOL_ERROR } ],
+              error: true
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/header_field.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # Field-value hygiene shared by the endpoint and the verified request:
+      # reject control bytes and comma-combined values, trim optional
+      # whitespace (RFC 9110 §5.5-5.6).
+      module HeaderField
+        CONTROLS = /[\x00-\x08\x0A-\x1F\x7F]/
+        OWS = /\A[\x20\x09]*(.*?)[\x20\x09]*\z/m
+
+        module_function
+
+        # The one exact value of a header that must not repeat: nil for
+        # missing, invalid, comma-combined, or empty-after-trim values.
+        def single(value)
+          return unless value.is_a?(String) && value.valid_encoding?
+          return if value.include?(",") || CONTROLS.match?(value)
+
+          candidate = trim_ows(value)
+          candidate unless candidate.nil? || candidate.empty?
+        end
+
+        def trim_ows(value)
+          value[OWS, 1]
+        end
+      end
+    end
+  end
+end