webmcp 0.0.1 → 0.1.1

data/lib/webmcp/form_helper.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module WebMCP
+  module FormOptions
+    module_function
+
+    def extract(options)
+      options = options.dup
+      metadata = options.delete(:webmcp) || options.delete("webmcp")
+      [options, metadata.nil? ? nil : Value.normalize(metadata)]
+    end
+
+    def form_attributes(metadata)
+      Value.keys!(metadata, %w[tool description autosubmit], "form webmcp")
+      Tool.validate_name!(metadata["tool"])
+      unless metadata["description"].is_a?(String) && !metadata["description"].empty?
+        raise DefinitionError, "form webmcp description must be a nonempty string"
+      end
+      if metadata.key?("autosubmit") && ![true, false].include?(metadata["autosubmit"])
+        raise DefinitionError, "autosubmit must be a boolean"
+      end
+      attrs = { "toolname" => metadata["tool"], "tooldescription" => metadata["description"] }
+      attrs["toolautosubmit"] = "toolautosubmit" if metadata["autosubmit"]
+      attrs
+    end
+
+    def field(options)
+      options, metadata = extract(options)
+      return options unless metadata
+      Value.keys!(metadata, %w[param_description], "field webmcp")
+      if metadata.key?("param_description")
+        raise DefinitionError, "param_description must be a string" unless metadata["param_description"].is_a?(String)
+        options["toolparamdescription"] = metadata["param_description"]
+      end
+      options
+    end
+
+    def select_options(options, html_options)
+      options, metadata = extract(options)
+      html_options, html_metadata = extract(html_options)
+      html_options[:webmcp] = html_metadata || metadata if html_metadata || metadata
+      [options, field(html_options)]
+    end
+  end
+
+  module FormHelper
+    def form_with(**options, &block)
+      options, metadata = FormOptions.extract(options)
+      options[:html] = (options[:html] || {}).merge(FormOptions.form_attributes(metadata)) if metadata
+      super(**options, &block)
+    end
+
+    def self.install!
+      ActionView::Helpers::FormHelper.prepend(self)
+      ActionView::Helpers::FormBuilder.prepend(FormBuilderOptions)
+      ActionView::Helpers::FormTagHelper.prepend(FormTagOptions)
+    end
+  end
+
+  module FormBuilderOptions
+    %i[text_field password_field hidden_field file_field text_area color_field search_field
+       telephone_field phone_field date_field time_field datetime_field datetime_local_field
+       month_field week_field url_field email_field number_field range_field].each do |method_name|
+      define_method(method_name) do |attribute, options = {}|
+        super(attribute, FormOptions.field(options))
+      end
+    end
+
+    def check_box(attribute, options = {}, checked_value = "1", unchecked_value = "0")
+      super(attribute, FormOptions.field(options), checked_value, unchecked_value)
+    end
+
+    def checkbox(attribute, options = {}, checked_value = "1", unchecked_value = "0")
+      super(attribute, FormOptions.field(options), checked_value, unchecked_value)
+    end
+
+    def radio_button(attribute, value, options = {})
+      super(attribute, value, FormOptions.field(options))
+    end
+
+    def select(attribute, choices = nil, options = {}, html_options = {}, &block)
+      options, html_options = FormOptions.select_options(options, html_options)
+      super(attribute, choices, options, html_options, &block)
+    end
+
+    def collection_select(attribute, collection, value_method, text_method, options = {}, html_options = {})
+      options, html_options = FormOptions.select_options(options, html_options)
+      super(attribute, collection, value_method, text_method, options, html_options)
+    end
+
+    def grouped_collection_select(attribute, collection, group_method, group_label_method, option_key_method, option_value_method, options = {}, html_options = {})
+      options, html_options = FormOptions.select_options(options, html_options)
+      super(attribute, collection, group_method, group_label_method, option_key_method, option_value_method, options, html_options)
+    end
+
+    %i[collection_check_boxes collection_checkboxes collection_radio_buttons].each do |method_name|
+      define_method(method_name) do |attribute, collection, value_method, text_method, options = {}, html_options = {}, &block|
+        options, html_options = FormOptions.select_options(options, html_options)
+        super(attribute, collection, value_method, text_method, options, html_options, &block)
+      end
+    end
+
+    def time_zone_select(attribute, priority_zones = nil, options = {}, html_options = {})
+      options, html_options = FormOptions.select_options(options, html_options)
+      super(attribute, priority_zones, options, html_options)
+    end
+
+    %i[weekday_select date_select time_select datetime_select].each do |method_name|
+      define_method(method_name) do |attribute, options = {}, html_options = {}|
+        options, html_options = FormOptions.select_options(options, html_options)
+        super(attribute, options, html_options)
+      end
+    end
+  end
+
+  module FormTagOptions
+    # Other scalar *_field_tag methods delegate to text_field_tag.
+    %i[text_field_tag text_area_tag select_tag].each do |method_name|
+      define_method(method_name) do |name, value = nil, options = {}|
+        super(name, value, FormOptions.field(options))
+      end
+    end
+
+    %i[check_box_tag checkbox_tag radio_button_tag].each do |method_name|
+      define_method(method_name) do |*args|
+        args[-1] = FormOptions.field(args.last) if args.last.is_a?(Hash)
+        super(*args)
+      end
+    end
+
+    private
+
+    def html_options_for_form(url_for_options, options)
+      options, metadata = FormOptions.extract(options)
+      options = options.merge(FormOptions.form_attributes(metadata)) if metadata
+      super(url_for_options, options)
+    end
+  end
+end

data/lib/webmcp/manifest.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module WebMCP
+  module Manifest
+    ESCAPES = { "<" => '\u003c', ">" => '\u003e', "&" => '\u0026', "\u2028" => '\u2028', "\u2029" => '\u2029' }.freeze
+    module_function
+
+    def normalize_transport(transport)
+      transport = Value.normalize(transport)
+      Value.keys!(transport, %w[csrf], "transport")
+      if transport.key?("csrf")
+        csrf = transport["csrf"]
+        Value.keys!(csrf, %w[source name header], "csrf")
+        unless %w[meta cookie].include?(csrf["source"]) && %w[name header].all? { |k| csrf[k].is_a?(String) && !csrf[k].empty? && !/[\x00-\x1f\x7f]/.match?(csrf[k]) }
+          raise DefinitionError, "csrf requires source meta/cookie and nonempty name/header"
+        end
+      end
+      transport
+    end
+
+    def build(tools, transport:)
+      transport = normalize_transport(transport)
+      entries = tools.map { |tool| tool.to_manifest_entry(transport) }
+      names = entries.map { |entry| entry["name"] }
+      raise DefinitionError, "duplicate tool names in manifest" unless names.uniq == names
+      { "webmcpManifestVersion" => 1, "transport" => transport, "tools" => entries }
+    end
+
+    def to_script_tag(hash, nonce: nil, autostart: true)
+      json = JSON.generate(Value.normalize(hash)).gsub(/[<>&\u2028\u2029]/, ESCAPES)
+      nonce_attr = nonce.nil? ? "" : %( nonce="#{Value.escape_html(nonce)}")
+      autostart_attr = autostart ? " data-webmcp-autostart" : ""
+      Value.html_safe(%(<script type="application/json" id="webmcp-manifest"#{nonce_attr}#{autostart_attr}>#{json}</script>))
+    end
+  end
+end

data/lib/webmcp/origin_trial.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module WebMCP
+  class OriginTrial
+    def initialize(app, token: nil, warn_on_oac_opt_out: true, logger: WebMCP.config.logger)
+      @app, @token, @logger = app, token.to_s, logger
+      @warn_on_oac_opt_out = warn_on_oac_opt_out
+      @warned = false
+      @warning_lock = Mutex.new
+    end
+
+    def call(env)
+      response = @app.call(env)
+      return response if @token.empty?
+      status, headers, body = response
+      unless headers.keys.any? { |key| key.downcase == "origin-trial" }
+        headers = headers.dup
+        # Rack 3 requires lowercase field names; Rack 2 preserves conventional casing.
+        key = env["rack.version"]&.first.to_i >= 3 || (defined?(Rack::RELEASE) && Rack::RELEASE.to_i >= 3) ? "origin-trial" : "Origin-Trial"
+        headers[key] = @token
+      end
+      oac_key = headers.keys.find { |key| key.downcase == "origin-agent-cluster" }
+      if @warn_on_oac_opt_out && headers[oac_key] == "?0"
+        @warning_lock.synchronize do
+          unless @warned
+            @logger&.warn("WebMCP: Origin-Agent-Cluster: ?0 may cause SecurityError in older Origin-Trial builds; header left unchanged")
+            @warned = true
+          end
+        end
+      end
+      [status, headers, body]
+    end
+
+    def self.meta_tag(token)
+      return Value.html_safe("") if token.nil? || token.to_s.empty?
+      Value.html_safe(%(<meta http-equiv="origin-trial" content="#{Value.escape_html(token)}">))
+    end
+  end
+end

data/lib/webmcp/projection.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module WebMCP
+  class Projection
+    def initialize(source, fingerprint)
+      @source = source
+      @metadata = Testing.source_metadata(source)
+      @fingerprint = Value.fingerprint(@metadata)
+      unless fingerprint == @fingerprint
+        raise DefinitionError, "source_fingerprint is missing or stale; current source_fingerprint: #{@fingerprint}"
+      end
+      @overrides = {}
+      @renames = {}
+      @notes = []
+    end
+
+    def rename_params(**map)
+      @renames.merge!(Value.normalize(map))
+    end
+
+    def input_schema(&block)
+      raise DefinitionError, "input_schema requires a projection block" unless block
+      @schema_block = block
+      @notes << "input_schema override"
+    end
+
+    %i[name title description max_response_chars].each do |field|
+      define_method(field) do |value|
+        @overrides[field] = value
+        @notes << "#{field} override"
+      end
+    end
+
+    def annotations(**values)
+      @overrides[:annotations] = values
+      @notes << "annotations explicitly declared"
+    end
+
+    def endpoint(**values)
+      @overrides[:endpoint] = values
+      @notes << "endpoint override"
+    end
+
+    def build(&block)
+      instance_eval(&block) if block
+      raise DefinitionError, "from_mcp requires an explicit annotations declaration (MCP hints are not inherited)" unless @overrides.key?(:annotations)
+      raise DefinitionError, "from_mcp requires an endpoint declaration" unless @overrides.key?(:endpoint)
+      schema = Value.normalize(@metadata["inputSchema"])
+      unless @renames.empty?
+        Schema.validate!(schema)
+        properties = schema.fetch("properties", {})
+        @renames.each do |old, replacement|
+          raise DefinitionError, "rename_params source is not a property: #{old}" unless properties.key?(old)
+          unless replacement.is_a?(String) && !replacement.empty?
+            raise DefinitionError, "rename_params destination must be a nonempty name"
+          end
+        end
+        names = properties.keys.map { |key| @renames.fetch(key, key) }
+        raise DefinitionError, "rename_params destinations collide" unless names.uniq == names
+        schema["properties"] = properties.to_h { |key, value| [@renames.fetch(key, key), value] }
+        schema["required"] = schema["required"].map { |key| @renames.fetch(key, key) } if schema.key?("required")
+        @renames.each { |old, replacement| @notes << "rename parameter #{old} -> #{replacement}" }
+      end
+      schema = @schema_block.call(schema) if @schema_block
+      Tool.new(name: @metadata["name"], title: @metadata["title"], description: @metadata["description"],
+               input_schema: schema, **@overrides, projection_notes: @notes,
+               source_fingerprint: @fingerprint, source: @source)
+    end
+  end
+end

data/lib/webmcp/railtie.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module WebMCP
+  class Railtie < Rails::Railtie
+    config.webmcp = ActiveSupport::OrderedOptions.new
+    config.webmcp.origin_trial_token = ENV["WEBMCP_ORIGIN_TRIAL_TOKEN"]
+
+    initializer "webmcp.configure" do |app|
+      if Gem::Version.new(Rails.version) < Gem::Version.new("7.1")
+        raise DefinitionError, "WebMCP Rails integration requires Rails >= 7.1"
+      end
+      token = app.config.webmcp.origin_trial_token
+      WebMCP.config.origin_trial_token = token
+      WebMCP.config.logger = Rails.logger if Rails.logger
+      app.middleware.use WebMCP::OriginTrial, token: token unless token.nil? || token.empty?
+    end
+
+    initializer "webmcp.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        WebMCP::FormHelper.install!
+        include WebMCP::ViewHelpers
+      end
+    end
+
+    initializer "webmcp.assets", after: :load_config_initializers do |app|
+      if app.config.respond_to?(:assets)
+        # The parent preserves the logical path webmcp/runtime.js in both pipelines.
+        root = File.expand_path("../../app/assets/javascripts", __dir__)
+        app.config.assets.paths << root
+        app.config.assets.paths << File.join(root, "webmcp")
+        if app.config.assets.respond_to?(:precompile)
+          app.config.assets.precompile += ["webmcp/runtime.js"]
+        end
+      end
+    end
+
+    config.after_initialize { WebMCP.freeze! }
+
+    rake_tasks do
+      load File.expand_path("../tasks/webmcp.rake", __dir__)
+    end
+  end
+end

data/lib/webmcp/registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WebMCP
+  class Registry
+    def initialize
+      @tools = {}
+    end
+
+    def register(tool)
+      raise DefinitionError, "registry is frozen" if frozen?
+      raise DefinitionError, "expected a WebMCP::Tool" unless tool.is_a?(Tool)
+      raise DefinitionError, "duplicate tool name: #{tool.name}" if @tools.key?(tool.name)
+      @tools[tool.name] = tool
+      tool
+    end
+
+    def fetch(name)
+      @tools.fetch(name.to_s) { raise DefinitionError, "unknown tool name: #{name}" }
+    end
+
+    def tools
+      @tools.values.freeze
+    end
+
+    def freeze!
+      @tools.freeze
+      freeze
+    end
+  end
+end

data/lib/webmcp/schema.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module WebMCP
+  module Schema
+    SCALARS = %w[string number integer boolean].freeze
+    METADATA = %w[enum description default minimum maximum maxLength maxItems].freeze
+    RESERVED = %w[__proto__ constructor prototype].freeze
+    module_function
+
+    def validate!(schema)
+      Value.keys!(schema, %w[type properties required description], "input_schema")
+      raise DefinitionError, 'input_schema type must be object' unless schema["type"] == "object"
+      properties = schema.fetch("properties", {})
+      Value.hash!(properties, "properties")
+      properties.each do |name, property|
+        raise DefinitionError, "reserved property name: #{name}" if RESERVED.include?(name)
+        validate_property!(property, name)
+      end
+      if schema.key?("description") && !schema["description"].is_a?(String)
+        raise DefinitionError, "schema description must be a string"
+      end
+      if schema.key?("required")
+        required = schema["required"]
+        unless required.is_a?(Array) && required.all? { |key| key.is_a?(String) && properties.key?(key) } && required.uniq == required
+          raise DefinitionError, "required must contain unique declared property names"
+        end
+      end
+      schema
+    end
+
+    def validate_property!(property, label, scalar_only: false)
+      Value.keys!(property, ["type", *METADATA, *(scalar_only ? [] : ["items"])], "property #{label}")
+      type = property["type"]
+      unless SCALARS.include?(type) || (!scalar_only && type == "array")
+        raise DefinitionError, "#{label}: only scalar properties and arrays of scalars are supported"
+      end
+      if type == "array"
+        validate_property!(property["items"], "#{label}.items", scalar_only: true)
+      elsif property.key?("items")
+        raise DefinitionError, "#{label}: items requires array type"
+      end
+      if property.key?("description") && !property["description"].is_a?(String)
+        raise DefinitionError, "#{label}: description must be a string"
+      end
+      %w[minimum maximum maxLength maxItems].each do |key|
+        next unless property.key?(key)
+        v = property[key]
+        unless v.is_a?(Integer) && (!%w[maxLength maxItems].include?(key) || v >= 0)
+          raise DefinitionError, "#{label}: #{key} must be an integer (lengths must be nonnegative)"
+        end
+      end
+      if property.key?("enum")
+        values = property["enum"]
+        unless values.is_a?(Array) && !values.empty? && values.all? { |v| matches?(v, property) }
+          raise DefinitionError, "#{label}: enum must be a nonempty array matching the property type"
+        end
+      end
+      if property.key?("default") && !matches?(property["default"], property)
+        raise DefinitionError, "#{label}: default must match the property type"
+      end
+    end
+
+    def matches?(value, schema)
+      case schema["type"]
+      when "string" then value.is_a?(String)
+      when "number", "integer" then value.is_a?(Integer)
+      when "boolean" then value == true || value == false
+      when "array" then value.is_a?(Array) && value.all? { |item| matches?(item, schema["items"]) }
+      else false
+      end
+    end
+  end
+end

data/lib/webmcp/testing.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module WebMCP
+  module Testing
+    module_function
+
+    def source_metadata(source)
+      raise DefinitionError, "MCP tool must respond to to_h" unless source.respond_to?(:to_h)
+      raw = source.to_h
+      Value.hash!(raw, "MCP tool metadata")
+      # Ignore MCP annotations (and other unrelated metadata) even for hashing.
+      selected = raw.select { |key, _| %w[name title description inputSchema].include?(key.to_s) }
+      Value.normalize(selected)
+    end
+
+    def current_source_fingerprint(source)
+      Value.fingerprint(source_metadata(source))
+    end
+
+    def assert_projection_fresh(tool)
+      raise DefinitionError, "tool is not an MCP projection" unless tool.source
+      current = current_source_fingerprint(tool.source)
+      unless tool.source_fingerprint == current
+        raise DefinitionError, "MCP projection #{tool.name} is stale; current source_fingerprint: #{current}"
+      end
+      true
+    end
+  end
+end

data/lib/webmcp/tool.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module WebMCP
+  class Tool
+    ANNOTATIONS = { "read_only" => "readOnlyHint", "untrusted_content" => "untrustedContentHint",
+                    "consequential" => "consequentialHint", "debugging" => "debugging" }.freeze
+    METHODS = %w[GET POST PATCH PUT DELETE].freeze
+    FORBIDDEN_PARAMS = %w[_method authenticity_token csrfmiddlewaretoken __proto__ constructor prototype].freeze
+    attr_reader :name, :description, :input_schema, :endpoint, :annotations, :title,
+                :max_response_chars, :projection_notes, :source_fingerprint, :source
+
+    def self.define(**options)
+      new(**options)
+    end
+
+    def self.from_mcp(source, source_fingerprint: nil, &block)
+      Projection.new(source, source_fingerprint).build(&block)
+    end
+
+    def self.validate_name!(name)
+      unless name.is_a?(String) && name.length.between?(1, 128) && /\A[A-Za-z0-9_.-]+\z/.match?(name)
+        raise DefinitionError, "tool name must be 1..128 characters from A-Z, a-z, 0-9, _, . and -"
+      end
+      name
+    end
+
+    def initialize(name:, description:, input_schema:, endpoint:, annotations: {}, title: nil,
+                   max_response_chars: nil, projection_notes: [], source_fingerprint: nil, source: nil)
+      @name = Value.normalize(name)
+      self.class.validate_name!(@name)
+      @description = Value.normalize(description)
+      unless @description.is_a?(String) && !@description.empty?
+        raise DefinitionError, "description must be a nonempty string"
+      end
+      @title = Value.normalize(title)
+      raise DefinitionError, "title must be a string" unless @title.nil? || @title.is_a?(String)
+      @input_schema = Schema.validate!(Value.normalize(input_schema))
+      @annotations = Value.normalize(annotations)
+      Value.hash!(@annotations, "annotations")
+      unless (@annotations.keys - ANNOTATIONS.keys).empty?
+        raise DefinitionError, "MCP and WebMCP annotation sets differ; WebMCP accepts only #{ANNOTATIONS.keys.join(', ')}; MCP destructive/idempotent/openWorld hints are not mapped"
+      end
+      unless @annotations.values.all? { |v| v == true || v == false }
+        raise DefinitionError, "annotations must be booleans"
+      end
+      @endpoint = validate_endpoint!(Value.normalize(endpoint))
+      @max_response_chars = Value.normalize(max_response_chars)
+      unless @max_response_chars.nil? || (@max_response_chars.is_a?(Integer) && @max_response_chars.positive?)
+        raise DefinitionError, "max_response_chars must be a positive integer"
+      end
+      @projection_notes = Value.normalize(projection_notes)
+      @source_fingerprint = Value.normalize(source_fingerprint)
+      @source = source # Keep the live source for drift checks; never freeze the SDK class.
+      [@name, @description, @title, @input_schema, @annotations, @endpoint,
+       @projection_notes, @source_fingerprint].each { |v| Value.deep_freeze(v) }
+      WebMCP.config.logger&.warn("WebMCP name exceeds Chrome's recommended 30-character budget: #{@name}") if @name.length > 30
+      WebMCP.config.logger&.warn("WebMCP description exceeds Chrome's recommended 500-character budget: #{@name}") if @description.length > 500
+      freeze
+    end
+
+    def to_manifest_entry(transport)
+      entry = { "name" => name, "description" => description, "inputSchema" => input_schema,
+                "annotations" => annotations.select { |_, v| v }.to_h { |k, v| [ANNOTATIONS.fetch(k), v] },
+                "endpoint" => { "path" => endpoint.fetch("path"), "method" => endpoint.fetch("method") } }
+      entry["title"] = title unless title.nil?
+      entry["maxResponseChars"] = max_response_chars unless max_response_chars.nil?
+      entry["endpoint"]["paramMap"] = endpoint["param_map"] unless endpoint["param_map"].empty?
+      entry["endpoint"]["arrayFormat"] = endpoint["array_format"] if endpoint["array_format"]
+      entry["fingerprint"] = Value.fingerprint(entry.merge("transport" => Manifest.normalize_transport(transport)))
+      Value.normalize(entry)
+    end
+
+    private
+
+    def validate_endpoint!(endpoint)
+      Value.keys!(endpoint, %w[path method param_map array_format], "endpoint")
+      path = endpoint["path"]
+      unless path.is_a?(String) && path.start_with?("/") && !path.start_with?("//") && !/[\\:\x00-\x1f\x7f]/.match?(path)
+        raise DefinitionError, "endpoint path must be same-origin, start with /, and contain no // prefix, backslash, colon or control character"
+      end
+      method = endpoint["method"].to_s.upcase
+      raise DefinitionError, "endpoint method must be GET, POST, PATCH, PUT or DELETE" unless METHODS.include?(method)
+      if method == "GET" && annotations["read_only"] != true
+        raise DefinitionError, "GET endpoints require read_only: true"
+      end
+      map = endpoint.fetch("param_map", {})
+      Value.hash!(map, "param_map")
+      properties = input_schema.fetch("properties", {})
+      map.each do |key, destination|
+        raise DefinitionError, "param_map key is not in schema properties: #{key}" unless properties.key?(key)
+        unless destination.is_a?(String) && /\A[A-Za-z][A-Za-z0-9_]*\z/.match?(destination) && !FORBIDDEN_PARAMS.include?(destination)
+          raise DefinitionError, "invalid or reserved param_map destination: #{destination.inspect}"
+        end
+      end
+      destinations = properties.keys.map { |key| map.fetch(key, key) }
+      raise DefinitionError, "param_map destinations collide" unless destinations.uniq == destinations
+      format = endpoint["array_format"]
+      raise DefinitionError, "array_format must be brackets or repeat" unless format.nil? || %w[brackets repeat].include?(format)
+      format ||= "brackets" if method == "GET" && properties.values.any? { |p| p["type"] == "array" }
+      { "path" => path, "method" => method, "param_map" => map, "array_format" => format }
+    end
+  end
+end

data/lib/webmcp/value.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module WebMCP
+  # Copy metadata, normalize Ruby symbol keys/values and reject non-JSON values.
+  module Value
+    module_function
+
+    def normalize(value, ancestors = [])
+      if value.is_a?(Hash) || value.is_a?(Array)
+        raise DefinitionError, "metadata cannot contain circular references" if ancestors.include?(value.object_id)
+        ancestors = ancestors + [value.object_id]
+      end
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, item), result|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise DefinitionError, "metadata keys must be strings or symbols"
+          end
+          key = key.to_s
+          raise DefinitionError, "duplicate metadata key: #{key}" if result.key?(key)
+          result[key] = normalize(item, ancestors)
+        end
+      when Array then value.map { |item| normalize(item, ancestors) }
+      when String
+        string = String.new(value).encode(Encoding::UTF_8)
+        raise DefinitionError, "metadata must be valid UTF-8" unless string.valid_encoding?
+        string
+      when Symbol then value.to_s
+      when Integer
+        raise DefinitionError, "metadata integers must be within +/-2^53" if value.abs > 2**53
+        value
+      when TrueClass, FalseClass, NilClass then value
+      else raise DefinitionError, "metadata must contain JSON values; floats are not supported"
+      end
+    rescue EncodingError => e
+      raise DefinitionError, "metadata must be UTF-8: #{e.message}"
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each { |k, v| deep_freeze(k); deep_freeze(v) }
+      when Array then value.each { |v| deep_freeze(v) }
+      end
+      value.freeze
+    end
+
+    def sorted(value)
+      case value
+      when Hash then value.keys.sort.to_h { |key| [key, sorted(value[key])] }
+      when Array then value.map { |item| sorted(item) }
+      else value
+      end
+    end
+
+    def fingerprint(value)
+      "sha256:#{Digest::SHA256.hexdigest(JSON.generate(sorted(normalize(value))))}"
+    end
+
+    def hash!(value, label)
+      raise DefinitionError, "#{label} must be an object" unless value.is_a?(Hash)
+      value
+    end
+
+    def keys!(value, allowed, label)
+      hash!(value, label)
+      unknown = value.keys - allowed
+      raise DefinitionError, "unsupported #{label} keys: #{unknown.join(', ')}" unless unknown.empty?
+    end
+
+    def html_safe(value)
+      value.respond_to?(:html_safe) ? value.html_safe : value
+    end
+
+    # String.new deliberately discards ActiveSupport's safe-string marker.
+    def escape_html(value)
+      CGI.escapeHTML(String.new(value.to_s))
+    end
+  end
+end

data/lib/webmcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WebMCP
-  VERSION = "0.0.1"
+  VERSION = "0.1.1"
 end