rosett-ai 1.3.3

data/lib/rosett_ai/mcp/governance.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    # Centralized MCP tool, resource, and prompt registration.
+    #
+    # Always loaded before plugins. Registers all built-in tools,
+    # resources, and prompts with the MCP server instance.
+    #
+    # @author hugo
+    # @author claude
+    module Governance
+      TOOL_CLASSES = [
+        Tools::ValidateTool,
+        Tools::CompileTool,
+        Tools::BehaviourListTool,
+        Tools::BehaviourShowTool,
+        Tools::BehaviourDisplayTool,
+        Tools::BehaviourManageTool,
+        Tools::DesignListTool,
+        Tools::DesignShowTool,
+        Tools::ConfigStatusTool,
+        Tools::ConfigCompileTool,
+        Tools::AdoptTool,
+        Tools::ComplyTool,
+        Tools::DoctorTool,
+        Tools::EnginesTool,
+        Tools::HooksStatusTool,
+        Tools::LicenseStatusTool,
+        Tools::ProjectTool,
+        Tools::ProvenanceTool,
+        Tools::ProvenanceWriteTool,
+        Tools::ToolingTool,
+        Tools::WorkflowTool,
+        Tools::WorkflowExecuteTool,
+        Tools::DocumentationStatusTool,
+        Tools::InitTool,
+        Tools::BackupTool,
+        Tools::ContentTool,
+        Tools::RetrofitTool,
+        Tools::RuleSearchTool,
+        Tools::CompileStatusTool,
+        Tools::HookPreviewTool,
+        Tools::HookInstallTool,
+        Tools::ContextQueryTool,
+        Tools::SchemaGetTool
+      ].freeze
+
+      RESOURCE_CLASSES = [
+        Resources::BehaviourResource,
+        Resources::DesignResource,
+        Resources::ProvenanceResource,
+        Resources::ConfigResource,
+        Resources::SchemaResource,
+        Resources::RulesResource,
+        Resources::HooksResource
+      ].freeze
+
+      PROMPT_CLASSES = [
+        Prompts::ValidationPrompt,
+        Prompts::CompilationPrompt,
+        Prompts::CompliancePrompt,
+        Prompts::DiagnosticsPrompt
+      ].freeze
+
+      KEYWORD_PARAM_TYPES = [:keyreq, :key].freeze
+
+      module_function
+
+      # @param server [MCP::Server]
+      def register(server)
+        register_tools(server)
+        register_resources(server)
+        register_prompts(server)
+      end
+
+      # @param server [MCP::Server]
+      def register_tools(server)
+        TOOL_CLASSES.each { |klass| register_tool(server, klass) }
+      end
+
+      # @param server [MCP::Server]
+      def register_resources(server)
+        resources = RESOURCE_CLASSES.map(&:new)
+        server.resources_list_handler { resources.flat_map(&:list) }
+        server.resources_read_handler do |uri:|
+          resource_name = uri.split('/').last
+          resource_class = find_resource_for_uri(resources, uri)
+          result = resource_class&.read(resource_name)
+          result&.fetch(:content, '')
+        end
+      end
+
+      # @param server [MCP::Server]
+      def register_prompts(server)
+        PROMPT_CLASSES.each do |klass|
+          prompt = klass.new
+          server.define_prompt(
+            name: klass::PROMPT_NAME,
+            description: klass::DESCRIPTION
+          ) do |args|
+            kwargs = (args || {}).transform_keys(&:to_sym)
+            prompt.call(**kwargs)
+          end
+        end
+      end
+
+      # @param server [MCP::Server]
+      # @param klass [Class] tool class with TOOL_NAME, DESCRIPTION, ANNOTATIONS
+      def register_tool(server, klass)
+        schema = klass.const_defined?(:INPUT_SCHEMA) ? klass::INPUT_SCHEMA : nil
+        server.define_tool(
+          name: klass::TOOL_NAME,
+          description: klass::DESCRIPTION,
+          annotations: snake_case_annotations(klass::ANNOTATIONS),
+          input_schema: schema
+        ) do |**args|
+          tool = klass.new
+          kwargs = Governance.build_kwargs(tool, args)
+          result = kwargs.empty? ? tool.call : tool.call(**kwargs)
+          MCP::Tool::Response.new([{ type: 'text', text: JSON.generate(result) }])
+        end
+      end
+
+      def find_resource_for_uri(resources, uri)
+        resources.find { |r| resource_matches_uri?(r, uri) }
+      end
+
+      def resource_matches_uri?(resource, uri)
+        resource.list.any? { |entry| entry[:uri] == uri }
+      end
+
+      # Convert camelCase annotation keys to snake_case symbols
+      # for the mcp gem's Annotations initializer.
+      def snake_case_annotations(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          snake = key.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+          result[snake] = value
+        end
+      end
+
+      # @param tool [Object] tool instance with #call
+      # @param args [Hash, nil] MCP arguments
+      def build_kwargs(tool, args)
+        return {} unless args.is_a?(Hash)
+
+        method_params = tool.method(:call).parameters
+        param_names = method_params.filter_map { |type, name| name if KEYWORD_PARAM_TYPES.include?(type) }
+
+        args.each_with_object({}) do |(key, value), kwargs|
+          sym = key.to_sym
+          kwargs[sym] = value if param_names.include?(sym)
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/http_security_config.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    # Typed HTTP security configuration hierarchy.
+    #
+    # Seven typed sub-config classes covering authentication, TLS,
+    # origin validation, rate limiting, CORS, and content type.
+    #
+    # @author hugo
+    # @author claude
+    class HttpSecurityConfig
+      attr_accessor :authentication, :tls, :origin, :rate_limiting,
+                    :max_request_size, :content_type_enforcement, :cors
+
+      def initialize
+        @authentication = AuthConfig.new
+        @tls = TlsConfig.new
+        @origin = OriginConfig.new
+        @rate_limiting = RateLimitConfig.new
+        @max_request_size = 1_048_576
+        @content_type_enforcement = true
+        @cors = CorsConfig.new
+      end
+
+      # Apply a configuration hash from YAML.
+      #
+      # @param hash [Hash] configuration hash
+      # @return [void]
+      def apply(hash)
+        return unless hash.is_a?(Hash)
+
+        @authentication.apply(hash['authentication']) if hash['authentication']
+        @tls.apply(hash['tls']) if hash['tls']
+        @origin.apply(hash['origin']) if hash['origin']
+        @rate_limiting.apply(hash['rate_limiting']) if hash['rate_limiting']
+        @cors.apply(hash['cors']) if hash['cors']
+        @max_request_size = hash['max_request_size'] if hash['max_request_size']
+        @content_type_enforcement = hash['content_type_enforcement'] if hash.key?('content_type_enforcement')
+      end
+
+      # Authentication sub-configuration.
+      class AuthConfig
+        attr_accessor :type, :key_source, :keyfile_path, :api_key_env
+
+        DEFAULT_KEYFILE_NAME = 'rosett-ai-mcp-keys.yml'
+
+        def initialize
+          @type = 'api_key'
+          @key_source = 'auto'
+          @keyfile_path = DEFAULT_KEYFILE_NAME
+          @api_key_env = 'RAI_MCP_API_KEY'
+        end
+
+        # Resolve the effective key source.
+        #
+        # @return [String] 'keyfile' or 'env'
+        def resolved_key_source
+          return @key_source unless @key_source == 'auto'
+
+          File.exist?(File.expand_path(@keyfile_path)) ? 'keyfile' : 'env'
+        end
+
+        def apply(hash)
+          return unless hash.is_a?(Hash)
+
+          @type = hash['type'] if hash['type']
+          @key_source = hash['key_source'] if hash['key_source']
+          @keyfile_path = hash['keyfile_path'] if hash['keyfile_path']
+          @api_key_env = hash['api_key_env'] if hash['api_key_env']
+        end
+      end
+
+      # TLS sub-configuration.
+      class TlsConfig
+        attr_accessor :enabled, :cert_path, :key_path
+
+        def initialize
+          @enabled = false
+          @cert_path = nil
+          @key_path = nil
+        end
+
+        def apply(hash)
+          return unless hash.is_a?(Hash)
+
+          @enabled = hash['enabled'] if hash.key?('enabled')
+          @cert_path = hash['cert_path'] if hash['cert_path']
+          @key_path = hash['key_path'] if hash['key_path']
+        end
+      end
+
+      # Origin validation sub-configuration.
+      class OriginConfig
+        DEFAULT_ORIGINS = ['http://localhost:*', 'http://127.0.0.1:*'].freeze
+
+        attr_accessor :allowed_origins, :strict_mode
+
+        def initialize
+          @allowed_origins = DEFAULT_ORIGINS.dup
+          @strict_mode = false
+        end
+
+        def apply(hash)
+          return unless hash.is_a?(Hash)
+
+          @allowed_origins = hash['allowed_origins'] if hash['allowed_origins']
+          @strict_mode = hash['strict_mode'] if hash.key?('strict_mode')
+        end
+      end
+
+      # Rate limiting sub-configuration.
+      class RateLimitConfig
+        attr_accessor :enabled, :unauthenticated_rpm, :authenticated_rpm
+
+        def initialize
+          @enabled = true
+          @unauthenticated_rpm = 60
+          @authenticated_rpm = 300
+        end
+
+        def apply(hash)
+          return unless hash.is_a?(Hash)
+
+          @enabled = hash['enabled'] if hash.key?('enabled')
+          @unauthenticated_rpm = hash['unauthenticated_rpm'] if hash['unauthenticated_rpm']
+          @authenticated_rpm = hash['authenticated_rpm'] if hash['authenticated_rpm']
+        end
+      end
+
+      # CORS sub-configuration.
+      class CorsConfig
+        attr_accessor :enabled, :origins, :methods, :headers, :max_age
+
+        def initialize
+          @enabled = false
+          @origins = []
+          @methods = ['POST', 'GET', 'DELETE']
+          @headers = ['Content-Type', 'Authorization', 'Accept', 'Mcp-Session-Id']
+          @max_age = 86_400
+        end
+
+        def apply(hash)
+          return unless hash.is_a?(Hash)
+
+          @enabled = hash['enabled'] if hash.key?('enabled')
+          @origins = hash['origins'] if hash['origins']
+          @methods = hash['methods'] if hash['methods']
+          @headers = hash['headers'] if hash['headers']
+          @max_age = hash['max_age'] if hash['max_age']
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/instructions.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    # Generates the MCP server instructions markdown for AI client
+    # auto-discovery. The instructions field is read by AI clients
+    # on session start to understand available tools, resources,
+    # and workflows without manual lookup.
+    #
+    # Content is generated dynamically from the registered tool and
+    # resource classes in {Governance}, ensuring documentation-tool
+    # parity (DES-RAI-MCP-002 constraint).
+    #
+    # @author hugo
+    # @author claude
+    module Instructions
+      # Tool categories for the instructions inventory.
+      # Maps category name to the tool class constants that belong to it.
+      CATEGORIES = {
+        'Discovery' => [
+          'rai_behaviour_list', 'rai_behaviour_show', 'rai_behaviour_display',
+          'rai_design_list', 'rai_design_show', 'rai_documentation_status',
+          'rai_rule_search', 'rai_schema_get', 'rai_compile_status'
+        ],
+        'Enforcement' => [
+          'rai_hook_preview', 'rai_hook_install', 'rai_context_query'
+        ],
+        'Management' => [
+          'rai_behaviour_manage', 'rai_compile', 'rai_config_compile',
+          'rai_validate', 'rai_init', 'rai_backup', 'rai_content', 'rai_retrofit'
+        ],
+        'Compliance' => [
+          'rai_comply', 'rai_provenance', 'rai_provenance_init', 'rai_adopt', 'rai_tooling'
+        ],
+        'Operations' => [
+          'rai_doctor', 'rai_project', 'rosett_ai_engines',
+          'rai_hooks_status', 'rai_config_status', 'rai_license_status'
+        ],
+        'Workflow' => [
+          'rai_workflow', 'rai_workflow_execute'
+        ]
+      }.freeze
+
+      # Resource URI prefixes for the instructions inventory.
+      RESOURCE_URIS = {
+        'rosett-ai://behaviour/{name}' => 'Behaviour YAML via 3-tier lookup (supports ?tier=xdg)',
+        'rosett-ai://design/{name}' => 'Design document YAML content',
+        'rosett-ai://provenance/' => 'AI provenance entries',
+        'rosett-ai://config/{scope}' => 'Settings for a scope (managed, user, project, local)',
+        'rosett-ai://schema/{name}' => 'JSON Schema content for validation',
+        'rosett-ai://rules/{name}' => 'Compiled rule markdown content',
+        'rosett-ai://hooks/{scope}' => 'Installed enforcement hook scripts'
+      }.freeze
+
+      module_function
+
+      # Generates the complete instructions markdown string.
+      #
+      # @return [String] markdown instructions for AI client consumption
+      def generate
+        sections = [
+          header_section,
+          tool_inventory_section,
+          resource_section,
+          scope_hierarchy_section,
+          workflow_section,
+          mutation_safety_section
+        ]
+        sections.join("\n\n")
+      end
+
+      # @return [String] header section
+      def header_section
+        <<~MARKDOWN.chomp
+          # Rosett-AI MCP Server
+
+          This server exposes rosett-ai configuration management tools via the
+          Model Context Protocol. Use this guide to select the right tool for
+          your task.
+
+          Version: #{RosettAi::VERSION}
+        MARKDOWN
+      end
+
+      # Generates the tool inventory grouped by category.
+      #
+      # @return [String] tool inventory markdown
+      def tool_inventory_section
+        lines = ["## Tool Inventory\n"]
+
+        CATEGORIES.each do |category, tool_names|
+          append_tool_table(lines, category, tool_entries_for(tool_names))
+        end
+
+        uncategorized = uncategorized_tools
+        append_tool_table(lines, 'Other', uncategorized) unless uncategorized.empty?
+
+        lines.join("\n")
+      end
+
+      # Appends a category tool table to the lines array.
+      #
+      # @param lines [Array<String>] accumulator
+      # @param heading [String] category heading
+      # @param entries [Array<Hash>] tool entries
+      # @return [void]
+      def append_tool_table(lines, heading, entries)
+        lines << "### #{heading}\n"
+        lines << '| Tool | Description | Read-only |'
+        lines << '|------|-------------|-----------|'
+        entries.each { |e| lines << format_tool_row(e) }
+        lines << ''
+      end
+
+      # Formats a single tool entry as a markdown table row.
+      #
+      # @param entry [Hash] tool entry with :name, :description, :read_only
+      # @return [String] markdown table row
+      def format_tool_row(entry)
+        ro = entry[:read_only] ? 'Yes' : 'No'
+        "| `#{entry[:name]}` | #{entry[:description]} | #{ro} |"
+      end
+
+      # Generates the resource URI documentation.
+      #
+      # @return [String] resource section markdown
+      def resource_section
+        table_rows = RESOURCE_URIS.map { |uri, desc| "| `#{uri}` | #{desc} |" }
+
+        [
+          "## Resources\n",
+          '| URI Pattern | Description |',
+          '|-------------|-------------|',
+          *table_rows,
+          '',
+          'Query parameters:',
+          '- `?tier=project|xdg|packaged` — request a specific tier (bypasses merge)',
+          '- `?strategy=first_wins|deep_merge|array_union` — override merge strategy'
+        ].join("\n")
+      end
+
+      # Explains the scope hierarchy for rule resolution.
+      #
+      # @return [String] scope hierarchy markdown
+      def scope_hierarchy_section
+        <<~MARKDOWN.chomp
+          ## Scope Hierarchy
+
+          Rules are resolved in priority order (highest scope wins):
+
+          1. **Project** (`.rosett-ai/conf/behaviour/`) — project-specific overrides
+          2. **XDG user** (`~/.config/rosett-ai/conf/behaviour/`) — user-authored global rules
+          3. **Packaged** (`/opt/rosett-ai/app/conf/behaviour/`) — default templates from installation
+
+          Compiled output goes to `~/.claude/rules/` via `rai_compile`.
+        MARKDOWN
+      end
+
+      # Documents common workflows.
+      #
+      # @return [String] workflow section markdown
+      def workflow_section
+        <<~MARKDOWN.chomp
+          ## Common Workflows
+
+          ### List and inspect behaviours
+
+          1. `rai_behaviour_list` — see all available behaviours
+          2. `rai_behaviour_show(name: "criticalthinking")` — inspect rules
+          3. Read `rosett-ai://behaviour/criticalthinking` — raw YAML content
+
+          ### Search and query rules
+
+          1. `rai_rule_search(keyword: "TMPDIR")` — find rules by keyword
+          2. `rai_context_query(tool_name: "Bash")` — what rules apply?
+          3. `rai_schema_get(schema_name: "behaviour")` — get validation schema
+
+          ### Compile rules for an AI engine
+
+          1. `rai_validate` — check all config files are valid
+          2. `rai_compile(engine: "claude", simulate: true)` — preview output
+          3. `rai_compile(engine: "claude")` — compile to `~/.claude/rules/`
+          4. `rai_compile_status` — check what needs recompilation
+
+          ### Install enforcement hooks
+
+          Rules with an `enforcement` block (type: enforceable, pattern, applies_to,
+          action) can be compiled into Claude Code PreToolUse hooks:
+
+          1. `rai_hook_preview(behaviour_name: "X")` — preview hook script
+          2. Review the output — check which rules are enforceable vs downgraded
+          3. `rai_hook_install(behaviour_name: "X", confirm: true)` — install
+
+          The enforcement pipeline validates patterns (rejects degenerate patterns
+          like `.*`), generates self-contained Ruby scripts, and installs them as
+          PreToolUse hooks. Invalid enforceable rules are downgraded to advisory.
+
+          ### Check project health
+
+          1. `rai_doctor` — run diagnostic checks
+          2. `rai_comply` — CRA, license, and SPDX header compliance
+          3. `rai_config_status` — configuration scope status
+        MARKDOWN
+      end
+
+      # Documents mutation safety rules.
+      #
+      # @return [String] mutation safety markdown
+      def mutation_safety_section
+        <<~MARKDOWN.chomp
+          ## Mutation Safety
+
+          Tools marked as **not read-only** perform writes. Before calling
+          mutation tools:
+
+          1. Present the action to the user and ask for confirmation
+          2. Prefer `simulate: true` first (where supported) to preview changes
+          3. The server does not enforce confirmation — the AI client must
+
+          Mutation tools: `rai_compile`, `rai_config_compile`, `rai_behaviour_manage`,
+          `rai_init`, `rai_backup`, `rai_content`, `rai_retrofit`,
+          `rai_provenance_init`, `rai_workflow_execute`, `rai_hook_install`.
+
+          `rai_hook_install` requires `confirm: true` and auto-backs up
+          existing hooks before writing. Use `rai_hook_preview` first.
+        MARKDOWN
+      end
+
+      # Builds tool entries for a list of tool names from Governance.
+      #
+      # @param tool_names [Array<String>] tool names to look up
+      # @return [Array<Hash>] tool entry hashes with :name, :description, :read_only
+      def tool_entries_for(tool_names)
+        tool_index = build_tool_index
+        tool_names.filter_map { |name| tool_index[name] }
+      end
+
+      # Returns tool entries not assigned to any category.
+      #
+      # @return [Array<Hash>] uncategorized tool entries
+      def uncategorized_tools
+        all_categorized = CATEGORIES.values.flatten
+        tool_index = build_tool_index
+        tool_index.except(*all_categorized)
+          .values
+      end
+
+      # Builds an index of tool name to entry hash from Governance.
+      #
+      # @return [Hash{String => Hash}] tool name to entry mapping
+      def build_tool_index
+        Governance::TOOL_CLASSES.each_with_object({}) do |klass, index|
+          name = klass::TOOL_NAME
+          index[name] = {
+            name: name,
+            description: klass::DESCRIPTION,
+            read_only: klass::ANNOTATIONS['readOnlyHint'] == true
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/key_hasher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'openssl'
+require 'securerandom'
+
+module RosettAi
+  module Mcp
+    # Cryptographic key hashing with per-key random salt.
+    #
+    # Uses SHA-256 with 16-byte random salt. Verification uses
+    # constant-time comparison via Rack::Utils.secure_compare.
+    #
+    # @author hugo
+    # @author claude
+    module KeyHasher
+      SALT_BYTES = 16
+      KEY_PREFIX = 'nncc_'
+
+      module_function
+
+      # Hash a plaintext API key with a random salt.
+      #
+      # @param plaintext [String] the plaintext key
+      # @return [String] salted hash in format "salt$digest"
+      def hash_key(plaintext)
+        salt = SecureRandom.hex(SALT_BYTES)
+        digest = OpenSSL::Digest::SHA256.hexdigest("#{salt}#{plaintext}")
+        "#{salt}$#{digest}"
+      end
+
+      # Verify a plaintext key against a stored hash.
+      #
+      # @param plaintext [String] the plaintext key to verify
+      # @param stored_hash [String] the stored "salt$digest" hash
+      # @return [Boolean] true if the key matches
+      def verify_key(plaintext, stored_hash)
+        salt, expected_digest = stored_hash.split('$', 2)
+        return false unless salt && expected_digest
+
+        actual_digest = OpenSSL::Digest::SHA256.hexdigest("#{salt}#{plaintext}")
+        secure_compare(actual_digest, expected_digest)
+      end
+
+      # Generate a new random API key with the Rosett-AI_ prefix.
+      #
+      # @return [String] a new API key
+      def generate_key
+        "#{KEY_PREFIX}#{SecureRandom.hex(24)}"
+      end
+
+      # Constant-time string comparison to prevent timing attacks.
+      #
+      # @param a [String] first string
+      # @param b [String] second string
+      # @return [Boolean] true if strings match
+      def secure_compare(a_str, b_str)
+        return false unless a_str.bytesize == b_str.bytesize
+
+        OpenSSL.fixed_length_secure_compare(a_str, b_str)
+      end
+    end
+  end
+end