hitch-rails 0.2.0

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Hitch
+  module MCP
+    module Internal
+      # HMAC-SHA256 digest over canonical JSON identity components, shared by
+      # rate-limit keying and observation identity. Each caller keeps its own
+      # salt, component layout, and output shape.
+      class HmacIdentity
+        MAX_COMPONENT_BYTES = 2_048
+
+        class << self
+          def digest(salt:, components:, key_generator:, unavailable_message:)
+            secret = key_generator.generate_key(salt, 32)
+            unless secret.is_a?(String) && secret.bytesize == 32
+              raise ArgumentError, unavailable_message
+            end
+
+            OpenSSL::HMAC.hexdigest("SHA256", secret, JSON.generate(components)).freeze
+          end
+
+          def component(value, invalid_message:)
+            unless value.is_a?(String) && value.valid_encoding? && !value.empty? &&
+                value.bytesize <= MAX_COMPONENT_BYTES
+              raise ArgumentError, invalid_message
+            end
+
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  module MCP
+    module Internal
+      # Exact binding of an incoming request to the canonical resource URI:
+      # scheme, path, query, effective port, and an allowlisted Host header
+      # parsed strictly (no lists, no controls, bounded length).
+      module HostAuthority
+        module_function
+
+        def allowed?(request)
+          resource = URI.parse(Hitch.configuration.resource_uri.to_s)
+          hostname, explicit_port = parse_authority(request.get_header("HTTP_HOST"))
+          resource_path = resource.path.empty? ? "/" : resource.path
+          return false unless hostname
+          return false unless request.get_header("rack.url_scheme") == resource.scheme
+          return false unless request.get_header("PATH_INFO") == resource_path
+          return false unless request.get_header("QUERY_STRING").to_s == resource.query.to_s
+
+          return false unless (explicit_port || resource.default_port) == resource.port
+
+          allowed_hosts = [ resource.hostname&.downcase, *Hitch.configuration.allowed_hosts ].compact.uniq
+          allowed_hosts.include?(hostname)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def parse_authority(value)
+          return [ nil, nil ] unless value.is_a?(String) && value.valid_encoding?
+          return [ nil, nil ] if value.empty? || value.bytesize > 512
+          return [ nil, nil ] if value.include?(",") || value.match?(/[\x00-\x20\x7F]/)
+
+          match = if value.start_with?("[")
+            /\A\[([0-9A-Fa-f:.]+)\](?::([0-9]{1,5}))?\z/.match(value)
+          else
+            /\A([^:\[\]]+)(?::([0-9]{1,5}))?\z/.match(value)
+          end
+          return [ nil, nil ] unless match
+
+          port = match[2] && Integer(match[2], exception: false)
+          return [ nil, nil ] if port && !port.between?(1, 65_535)
+
+          [ match[1].downcase, port ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Hitch
+  module MCP
+    module Internal
+      # Shared recursive helpers for the JSON-value structures that cross MCP
+      # boundaries. Keys are never symbolized (INV-MCP-007).
+      module JsonValues
+        # Every rejecting boundary supplies its own on_invalid; this fires only
+        # when a policy rejects without one.
+        DEFAULT_HANDLER = lambda do |reason, _detail|
+          raise ArgumentError, "JSON value copy rejected (#{reason})"
+        end
+
+        module_function
+
+        # String/Symbol-indifferent read that prefers the key exactly as given.
+        def read(hash, key)
+          return unless hash.is_a?(Hash)
+          return hash[key] if hash.key?(key)
+
+          hash[key.is_a?(Symbol) ? key.to_s : key.to_sym]
+        end
+
+        # The one deep JSON copier. Each boundary states its policy:
+        #   keys:       :as_is, :string (String only), :stringify_symbols,
+        #               :preserve (String copied, Symbol kept), or :to_s
+        #   symbols:    Symbol values — :keep, :to_s, or :reject
+        #   foreign:    values outside the JSON universe — :keep, :to_s, or :reject
+        #   finite:     reject non-finite Floats
+        #   duplicates: keys that collide after normalization — :replace or :reject
+        #   freeze:     deep-freeze the copy
+        #   max_depth / max_objects: structural caps
+        # on_invalid receives (reason, detail) and either raises or returns the
+        # replacement for the entire copy. Reasons: :recursive, :depth,
+        # :objects, :key, :duplicate_key, :non_finite, :foreign.
+        def copy(value, keys: :as_is, symbols: :keep, foreign: :keep, finite: false,
+          duplicates: :replace, freeze: false, max_depth: nil, max_objects: nil,
+          on_invalid: DEFAULT_HANDLER)
+          Copier.new(
+            keys:, symbols:, foreign:, finite:, duplicates:,
+            freeze:, max_depth:, max_objects:, on_invalid:
+          ).call(value)
+        end
+
+        def deep_string_copy_and_freeze(value)
+          copy(value, keys: :to_s, freeze: true)
+        end
+
+        def deep_freeze(value)
+          case value
+          when Hash
+            value.each { |key, child| deep_freeze(key); deep_freeze(child) }
+          when Array
+            value.each { |child| deep_freeze(child) }
+          end
+          value.freeze
+        end
+
+        class Copier
+          REPLACED = Object.new
+          private_constant :REPLACED
+
+          def initialize(keys:, symbols:, foreign:, finite:, duplicates:,
+            freeze:, max_depth:, max_objects:, on_invalid:)
+            @keys = keys
+            @symbols = symbols
+            @foreign = foreign
+            @finite = finite
+            @duplicates = duplicates
+            @freeze = freeze
+            @max_depth = max_depth
+            @max_objects = max_objects
+            @on_invalid = on_invalid
+            @seen = Set.new
+            @objects = 0
+          end
+
+          def call(value)
+            catch(REPLACED) { walk(value, 1) }
+          end
+
+          private
+
+          def walk(value, depth)
+            invalid!(:depth, nil) if @max_depth && depth > @max_depth
+            return if value.nil?
+
+            copied = case value
+            when Hash then walk_hash(value, depth)
+            when Array then walk_array(value, depth)
+            when String then value.dup
+            when Symbol then symbol_value(value)
+            when Float
+              invalid!(:non_finite, nil) if @finite && !value.finite?
+
+              value
+            when Integer, TrueClass, FalseClass
+              value
+            else
+              foreign_value(value)
+            end
+            @freeze ? copied.freeze : copied
+          end
+
+          def walk_hash(hash, depth)
+            invalid!(:recursive, nil) unless @seen.add?(hash.object_id)
+
+            @objects += 1
+            invalid!(:objects, nil) if @max_objects && @objects > @max_objects
+
+            hash.each_with_object({}) do |(key, child), result|
+              copied_key = copy_key(key)
+              invalid!(:duplicate_key, copied_key) if @duplicates == :reject && result.key?(copied_key)
+
+              result[copied_key] = walk(child, depth + 1)
+            end
+          ensure
+            @seen.delete(hash.object_id)
+          end
+
+          def walk_array(array, depth)
+            invalid!(:recursive, nil) unless @seen.add?(array.object_id)
+
+            array.map { |child| walk(child, depth + 1) }
+          ensure
+            @seen.delete(array.object_id)
+          end
+
+          def copy_key(key)
+            case @keys
+            when :as_is then key
+            when :to_s then key.to_s
+            when :string
+              invalid!(:key, key) unless key.is_a?(String)
+
+              key.dup.freeze
+            when :stringify_symbols
+              case key
+              when String then key.dup.freeze
+              when Symbol then key.to_s
+              else invalid!(:key, key)
+              end
+            when :preserve
+              case key
+              when String then key.dup.freeze
+              when Symbol then key
+              else invalid!(:key, key)
+              end
+            else
+              raise ArgumentError, "unknown keys policy #{@keys.inspect}"
+            end
+          end
+
+          def symbol_value(value)
+            case @symbols
+            when :keep then value
+            when :to_s then value.to_s
+            when :reject then invalid!(:foreign, nil)
+            else raise ArgumentError, "unknown symbols policy #{@symbols.inspect}"
+            end
+          end
+
+          def foreign_value(value)
+            case @foreign
+            when :keep then value
+            when :to_s then value.to_s
+            when :reject then invalid!(:foreign, nil)
+            else raise ArgumentError, "unknown foreign policy #{@foreign.inspect}"
+            end
+          end
+
+          def invalid!(reason, detail)
+            throw REPLACED, @on_invalid.call(reason, detail)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # A client must learn nothing from a host failure; the developer who
+      # wrote it must learn everything. Those are two audiences and only the
+      # first is a threat, so in development and test the real exception goes
+      # to the local log. Callers' wire responses are unchanged, and
+      # production stays silent.
+      module LocalDiagnosis
+        module_function
+
+        def report(subject, error = nil)
+          return unless Rails.env.local?
+
+          lines = [ "[hitch] #{subject}" ]
+          if error
+            lines << "  #{error.class}: #{error.message}"
+            lines.concat(Array(error.backtrace).first(5).map { |line| "    #{line}" })
+          end
+          Rails.logger&.error(lines.join("\n"))
+          nil
+        # Diagnosing a failure must not become one.
+        rescue StandardError, SystemStackError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # Strict media negotiation for the endpoint (RFC 7231 §5.3): the request
+      # body must be exactly application/json, and Accept must admit both
+      # response framings the protocol may use.
+      module MediaType
+        ACCEPT_TYPES = %w[application/json text/event-stream].freeze
+        MEDIA_TYPE_PATTERN = %r{\A[A-Za-z0-9!#$%&'*+.^_`|~-]+/[A-Za-z0-9!#$%&'*+.^_`|~-]+\z}
+        PARAMETER_PATTERN = /\A[A-Za-z0-9!#$%&'*+.^_`|~-]+=[^;\s]+\z/
+        QUALITY_PATTERN = /\A(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)\z/
+
+        module_function
+
+        def json_content_type?(value)
+          return false unless value.is_a?(String) && value.valid_encoding?
+          return false if value.empty? || value.include?(",") || HeaderField::CONTROLS.match?(value)
+
+          media_type, *parameters = value.split(";", -1).map { |part| HeaderField.trim_ows(part) }
+          return false unless media_type&.downcase == "application/json"
+
+          parameters.all? { |parameter| parameter&.match?(PARAMETER_PATTERN) }
+        end
+
+        def accepts_required_types?(value)
+          return false unless value.is_a?(String) && value.valid_encoding?
+          return false if value.empty? || HeaderField::CONTROLS.match?(value)
+
+          accepted = {}
+          value.split(",", -1).each do |entry|
+            media_type, quality = accept_entry(entry)
+            return false unless media_type
+
+            accepted[media_type] = true if ACCEPT_TYPES.include?(media_type) && quality.positive?
+          end
+          ACCEPT_TYPES.all? { |media_type| accepted[media_type] }
+        end
+
+        def accept_entry(entry)
+          media_type, *parameters = entry.split(";", -1).map { |part| HeaderField.trim_ows(part) }
+          return [ nil, nil ] unless media_type&.match?(MEDIA_TYPE_PATTERN)
+
+          quality = 1.0
+          quality_seen = false
+          parameters.each do |parameter|
+            name, raw_value = parameter.to_s.split("=", 2)
+            return [ nil, nil ] unless name && raw_value
+            next unless name.casecmp?("q")
+            return [ nil, nil ] if quality_seen || !raw_value.match?(QUALITY_PATTERN)
+
+            quality_seen = true
+            quality = raw_value.to_f
+          end
+          [ media_type.downcase, quality ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Hitch
+  module MCP
+    module Internal
+      # Request-local structural telemetry. The state never crosses the public
+      # Context or SDK server_context boundary, and publication temporarily
+      # detaches it so hostile subscribers cannot recursively observe their own
+      # work as part of the request.
+      class Observation
+        REQUEST_EVENT = "request.hitch_mcp"
+        INVOCATION_EVENT = "invocation.hitch_mcp"
+        IDENTITY_SALT = "hitch/mcp/observation/v1"
+        CURRENT_REQUEST_KEY = :hitch_mcp_observation_request
+        REQUEST_ID_PATTERN = /\A[0-9a-f]{32}\z/
+        PRINCIPAL_TYPE_PATTERN = /\A[A-Za-z_][A-Za-z0-9_:]{0,254}\z/
+        PROTOCOL_OUTCOMES = {
+          -32_700 => "parse_error",
+          -32_600 => "invalid_request",
+          -32_601 => "method_not_found",
+          -32_602 => "invalid_params",
+          -32_603 => "internal_error",
+          -32_020 => "header_mismatch",
+          -32_022 => "unsupported_protocol"
+        }.freeze
+        HTTP_OUTCOMES = {
+          200 => "complete",
+          400 => "bad_request",
+          401 => "unauthorized",
+          403 => "forbidden",
+          404 => "not_found",
+          405 => "method_not_allowed",
+          406 => "not_acceptable",
+          413 => "request_too_large",
+          415 => "unsupported_media_type",
+          429 => "rate_limited",
+          503 => "service_unavailable"
+        }.freeze
+        HTTP_TERMINAL_OUTCOMES = [ 406, 413, 415 ].freeze
+
+        class RequestState
+          attr_reader :request_id
+
+          def initialize
+            @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            @request_id = SecureRandom.hex(16).freeze
+            @method = nil
+            @tool_name = nil
+            @principal_type = nil
+            @principal_key = nil
+            @client_key = nil
+            @protocol_code = nil
+            @request_bytes = 0
+            @finished = false
+          end
+
+          def authenticated!(principal:, client_id:)
+            principal_type, principal_key, client_key = Observation.identity_keys(
+              principal:,
+              client_id:
+            )
+            @principal_type = principal_type
+            @principal_key = principal_key
+            @client_key = client_key
+            nil
+          rescue StandardError, SystemStackError
+            Observation.report_failure(REQUEST_EVENT, "identity")
+            nil
+          end
+
+          def request_bytes!(value)
+            @request_bytes = value if value.is_a?(Integer) && value >= 0
+            nil
+          end
+
+          def verified!(request)
+            method = JsonValues.read(request, "method")
+            @method = method.dup.freeze if Protocol::METHODS.include?(method)
+            nil
+          rescue StandardError, SystemStackError
+            Observation.report_failure(REQUEST_EVENT, "verified_request")
+            nil
+          end
+
+          def tool_resolved!(name)
+            @tool_name = name.dup.freeze if Protocol.tool_name?(name)
+            nil
+          end
+
+          def protocol_response!(response)
+            error = JsonValues.read(response, "error")
+            code = JsonValues.read(error, "code")
+            @protocol_code = code if code.is_a?(Integer)
+            nil
+          rescue StandardError, SystemStackError
+            Observation.report_failure(REQUEST_EVENT, "protocol_response")
+            nil
+          end
+
+          def start_invocation(tool_name:)
+            return if @finished
+            return unless Protocol.tool_name?(tool_name)
+
+            InvocationState.new(request_id:, tool_name:)
+          end
+
+          def finish!(response:)
+            return if @finished
+
+            @finished = true
+            http_status = response.status.to_i
+            payload = {
+              schema_version: 1,
+              request_id:,
+              method: @method,
+              tool_name: @tool_name,
+              principal_type: @principal_type,
+              principal_key: @principal_key,
+              client_key: @client_key,
+              http_status:,
+              protocol_code: @protocol_code,
+              outcome: outcome(http_status),
+              request_bytes: @request_bytes,
+              response_bytes: Observation.response_bytes(response),
+              duration_ms: duration_ms
+            }.freeze
+            Observation.publish(REQUEST_EVENT, payload)
+            nil
+          rescue StandardError, SystemStackError
+            Observation.report_failure(REQUEST_EVENT, "request_finish")
+            nil
+          end
+
+          private
+
+          def outcome(http_status)
+            return HTTP_OUTCOMES.fetch(http_status) if HTTP_TERMINAL_OUTCOMES.include?(http_status)
+
+            PROTOCOL_OUTCOMES.fetch(@protocol_code) do
+              HTTP_OUTCOMES.fetch(http_status, "http_error")
+            end
+          end
+
+          def duration_ms
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+            [ (elapsed * 1_000).round(3), 0.0 ].max
+          end
+        end
+
+        class InvocationState
+          def initialize(request_id:, tool_name:)
+            @request_id = request_id
+            @tool_name = tool_name.dup.freeze
+            @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            @argument_policy = "not_reached"
+            @executed = false
+            @result_category = "generic_error"
+            @finished = false
+          end
+
+          def argument_policy_allowed!
+            @argument_policy = "allowed"
+            nil
+          end
+
+          def execution_started!
+            @executed = true
+            nil
+          end
+
+          def result_normalized!(kind:)
+            @result_category = kind == :error ? "explicit_error" : "success"
+            nil
+          end
+
+          def failed!(phase:, expected_denial:)
+            if phase == :authorization
+              @argument_policy = expected_denial ? "denied" : "failed"
+            end
+            @result_category = "generic_error"
+            nil
+          end
+
+          def finish!
+            return if @finished
+
+            @finished = true
+            payload = {
+              schema_version: 1,
+              request_id: @request_id,
+              tool_name: @tool_name,
+              availability: "available",
+              argument_policy: @argument_policy,
+              executed: @executed,
+              result_category: @result_category,
+              duration_ms: duration_ms
+            }.freeze
+            Observation.publish(INVOCATION_EVENT, payload)
+            nil
+          rescue StandardError, SystemStackError
+            Observation.report_failure(INVOCATION_EVENT, "invocation_finish")
+            nil
+          end
+
+          private
+
+          def duration_ms
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+            [ (elapsed * 1_000).round(3), 0.0 ].max
+          end
+        end
+
+        class << self
+          def with_request_state
+            previous = ActiveSupport::IsolatedExecutionState[CURRENT_REQUEST_KEY]
+            state = begin
+              created = RequestState.new
+              ActiveSupport::IsolatedExecutionState[CURRENT_REQUEST_KEY] = created
+              created
+            rescue StandardError, SystemStackError
+              report_failure(REQUEST_EVENT, "request_start")
+              nil
+            end
+            yield state
+          ensure
+            begin
+              if previous
+                ActiveSupport::IsolatedExecutionState[CURRENT_REQUEST_KEY] = previous
+              else
+                ActiveSupport::IsolatedExecutionState.delete(CURRENT_REQUEST_KEY)
+              end
+            rescue StandardError, SystemStackError
+              report_failure(REQUEST_EVENT, "request_cleanup")
+            end
+          end
+
+          def start_invocation(tool_name:)
+            current_request&.start_invocation(tool_name:)
+          rescue StandardError, SystemStackError
+            report_failure(INVOCATION_EVENT, "invocation_start")
+            nil
+          end
+
+          def current_request_id
+            correlation_id(current_request&.request_id)
+          rescue StandardError, SystemStackError
+            nil
+          end
+
+          def publish(event_name, payload)
+            previous = ActiveSupport::IsolatedExecutionState[CURRENT_REQUEST_KEY]
+            ActiveSupport::IsolatedExecutionState.delete(CURRENT_REQUEST_KEY)
+            ActiveSupport::Notifications.instrument(event_name, payload)
+          rescue StandardError, SystemStackError
+            report_failure(event_name, "subscriber")
+            nil
+          ensure
+            if previous
+              ActiveSupport::IsolatedExecutionState[CURRENT_REQUEST_KEY] = previous
+            else
+              ActiveSupport::IsolatedExecutionState.delete(CURRENT_REQUEST_KEY)
+            end
+          end
+
+          def identity_keys(principal:, client_id:, key_generator: Rails.application.key_generator)
+            record_class = principal.class.respond_to?(:base_class) ? principal.class.base_class : principal.class
+            principal_type = record_class.name
+            unless principal_type.is_a?(String) && PRINCIPAL_TYPE_PATTERN.match?(principal_type)
+              raise ArgumentError, "MCP observation principal type is invalid"
+            end
+
+            invalid_message = "MCP observation identity is invalid"
+            principal_id = HmacIdentity.component(principal.id.to_s, invalid_message:)
+            client = HmacIdentity.component(client_id, invalid_message:)
+            principal_key = identity_digest([ "principal", principal_type, principal_id ], key_generator)
+            client_key = identity_digest([ "client", client ], key_generator)
+            [ principal_type.dup.freeze, principal_key, client_key ].freeze
+          end
+
+          def response_bytes(response)
+            body = response.body
+            return body.bytesize if body.is_a?(String)
+            return 0 if body.nil?
+
+            Array(body).sum { |part| part.to_s.bytesize }
+          end
+
+          def report_failure(event_name, category)
+            SanitizedReport.emit(
+              source: "hitch.mcp.observation",
+              message: "Hitch MCP observation delivery failed",
+              context: {
+                hitch_mcp_category: "observation_#{category}".freeze,
+                hitch_mcp_event: event_name.dup.freeze
+              }.freeze
+            )
+          rescue StandardError, SystemStackError
+            nil
+          end
+
+          private
+
+          def correlation_id(request_id)
+            return unless request_id.instance_of?(String) && REQUEST_ID_PATTERN.match?(request_id)
+
+            request_id.dup.freeze
+          end
+
+          def current_request
+            ActiveSupport::IsolatedExecutionState[CURRENT_REQUEST_KEY]
+          end
+
+          def identity_digest(components, key_generator)
+            HmacIdentity.digest(
+              salt: IDENTITY_SALT,
+              components: components,
+              key_generator: key_generator,
+              unavailable_message: "MCP observation key is unavailable"
+            )
+          end
+        end
+
+        private_constant :RequestState, :InvocationState,
+          :REQUEST_EVENT, :INVOCATION_EVENT, :IDENTITY_SALT,
+          :CURRENT_REQUEST_KEY, :PRINCIPAL_TYPE_PATTERN,
+          :REQUEST_ID_PATTERN, :PROTOCOL_OUTCOMES, :HTTP_OUTCOMES,
+          :HTTP_TERMINAL_OUTCOMES
+      end
+    end
+  end
+end