maquina-generators 0.9.0 → 0.10.0

data/lib/generators/maquina/backstage_signin/backstage_signin.rb

@@ -0,0 +1,245 @@
+module Maquina
+  module Generators
+    # Puts the backstage behind the app's own Clave sign-in instead of the
+    # shared Basic Auth login. The dashboard generators (solid_errors,
+    # mission_control_jobs, security) call install_backstage_signin after they
+    # write their files, so whichever runs, and in whatever order, the backstage
+    # ends up on the sign-in when Clave is installed.
+    #
+    # Who gets in is User#backstage_access?: an unblocked user whose email is
+    # listed under backstage.emails in credentials. The same predicate gates
+    # the admin-only MCP tools, which is why maquina:mcp calls
+    # add_backstage_access_to_user too.
+    #
+    # Each step edits a snippet the generators wrote. One that is not found
+    # (the app changed it) is left alone and named in backstage_signin_pending
+    # for the post-install message.
+    #
+    # Every method is private: a public method on a generator is a Thor step.
+    module BackstageSignin
+      TEMPLATES = File.expand_path("templates", __dir__)
+
+      USER_MODEL = "app/models/user.rb"
+      BACKSTAGE_CONTROLLER = "app/controllers/backstage_controller.rb"
+      DASHBOARD_CONTROLLER = "app/controllers/backstage_dashboard_controller.rb"
+      SECURITY_CONTROLLER = "app/controllers/backstage/security_controller.rb"
+      SOLID_ERRORS_INITIALIZER = "config/initializers/solid_errors.rb"
+      MISSION_CONTROL_INITIALIZER = "config/initializers/mission_control.rb"
+      ACCESS_TEST = "test/integration/backstage_access_test.rb"
+
+      BACKSTAGE_CLASS = /^class BackstageController < ActionController::Base\n/
+      CLASS_END = /^end\s*\z/
+      BASIC_AUTH_ACTIONS = /\n  before_action :require_backstage_credentials\n  before_action :authenticate(_backstage)?\n/
+      # The private section both controllers end with: nothing in it but the
+      # Basic Auth helpers.
+      DASHBOARD_BASIC_AUTH = /\n\n  private\n\n  # Closed \(503\) until credentials\.backstage is set\..*\n  end\n(?=end\n?\z)/m
+      SECURITY_BASIC_AUTH = /\n\n  private\n\n  def authenticate\n.*\n  end\n(?=end\n?\z)/m
+      SECURITY_HEADER = /# Rack::Attack's last week, read from the `security` database\. Behind the same\n.*\n.*so it is never left open\.\n/
+      SOLID_ERRORS_BASIC_AUTH = /\n  backstage = Rails\.application\.credentials\.backstage \|\| \{\}\n\n  config\.solid_errors\.username = .*\n  config\.solid_errors\.password = .*\n/
+      MISSION_CONTROL_BASIC_AUTH = /  backstage = Rails\.application\.credentials\.backstage \|\| \{\}\n\n  MissionControl::Jobs\.http_basic_auth_user = .*\n  MissionControl::Jobs\.http_basic_auth_password = .*\n/
+
+      # The people the generated access test signs in as.
+      USER_FIXTURES = {
+        "backstage_operator" => {"email_address" => "backstage-operator@example.com", "name" => "Backstage Operator", "role" => "admin"},
+        "backstage_member" => {"email_address" => "backstage-member@example.com", "name" => "Backstage Member", "role" => "admin"}
+      }.freeze
+
+      private
+
+      def clave_installed?
+        # EmailVerification is Clave's own. Rails' authentication generator
+        # (maquina:registration) also writes the other two, but its User has no
+        # blocked?, so that app keeps Basic Auth.
+        [USER_MODEL, "app/models/email_verification.rb", "app/controllers/concerns/authentication.rb"]
+          .all? { |path| backstage_file?(path) }
+      end
+
+      def backstage_signin_pending
+        @backstage_signin_pending ||= []
+      end
+
+      # Returns true when the backstage is (now) behind the sign-in.
+      def install_backstage_signin
+        return false unless clave_installed?
+
+        add_backstage_access_to_user
+        convert_backstage_controller
+        convert(DASHBOARD_CONTROLLER, done_unless: "require_backstage_credentials") do
+          gsub_file DASHBOARD_CONTROLLER, BASIC_AUTH_ACTIONS, ""
+          gsub_file DASHBOARD_CONTROLLER, DASHBOARD_BASIC_AUTH, "\n"
+          gsub_file DASHBOARD_CONTROLLER, "under the same backstage Basic auth.", "behind the same backstage sign-in."
+        end
+        convert(SECURITY_CONTROLLER, done_unless: "require_backstage_credentials") do
+          gsub_file SECURITY_CONTROLLER, BASIC_AUTH_ACTIONS, ""
+          gsub_file SECURITY_CONTROLLER, SECURITY_BASIC_AUTH, "\n"
+          gsub_file SECURITY_CONTROLLER, SECURITY_HEADER,
+            "# Rack::Attack's last week, read from the `security` database. Behind the\n" \
+            "# backstage sign-in, like every page BackstageController serves.\n"
+        end
+        convert(SOLID_ERRORS_INITIALIZER, done_unless: "config.solid_errors.password =") do
+          gsub_file SOLID_ERRORS_INITIALIZER, SOLID_ERRORS_BASIC_AUTH,
+            "\n  # Signed-in backstage users only, through BackstageController. Leave\n" \
+            "  # username and password unset: a password turns Basic Auth back on.\n"
+        end
+        convert(MISSION_CONTROL_INITIALIZER, done_unless: "http_basic_auth_user") do
+          gsub_file MISSION_CONTROL_INITIALIZER, MISSION_CONTROL_BASIC_AUTH,
+            "  # Signed-in backstage users only, through BackstageController.\n" \
+            "  MissionControl::Jobs.http_basic_auth_enabled = false\n"
+        end
+        create_backstage_access_test
+        true
+      end
+
+      # User.backstage_emails and User#backstage_access?. Also called by
+      # maquina:mcp, whose admin-only tools use the same gate.
+      def add_backstage_access_to_user
+        return unless backstage_file?(USER_MODEL)
+
+        content = File.read(File.join(destination_root, USER_MODEL))
+        return if content.include?("def backstage_access?")
+
+        if content.match?(/^  private$/)
+          inject_into_file USER_MODEL, backstage_access_methods, before: /^  private$/
+        elsif content.match?(CLASS_END)
+          inject_into_file USER_MODEL, "\n#{backstage_access_methods.chomp}", before: CLASS_END
+        else
+          backstage_signin_pending << USER_MODEL
+        end
+      end
+
+      def convert_backstage_controller
+        return unless backstage_file?(BACKSTAGE_CONTROLLER)
+
+        content = File.read(File.join(destination_root, BACKSTAGE_CONTROLLER))
+        return if content.include?("require_backstage_access")
+        return backstage_signin_pending << BACKSTAGE_CONTROLLER unless content.match?(BACKSTAGE_CLASS) && content.match?(CLASS_END)
+
+        inject_into_file BACKSTAGE_CONTROLLER, backstage_controller_header, after: BACKSTAGE_CLASS
+        inject_into_file BACKSTAGE_CONTROLLER, backstage_controller_private, before: CLASS_END
+      end
+
+      # Runs the edits when the file still has Basic Auth (`done_unless`), then
+      # checks they took. A file the app has reshaped keeps its Basic Auth and
+      # is named in the post-install message.
+      def convert(path, done_unless:)
+        full_path = File.join(destination_root, path)
+        return unless File.exist?(full_path)
+        return unless File.read(full_path).include?(done_unless)
+
+        yield
+        backstage_signin_pending << path if File.read(full_path).include?(done_unless)
+      end
+
+      def create_backstage_access_test
+        return unless backstage_file?("test/test_helpers/session_test_helper.rb")
+
+        create_file ACCESS_TEST, File.read(File.join(TEMPLATES, ACCESS_TEST)) unless backstage_file?(ACCESS_TEST)
+        append_backstage_fixture "test/fixtures/accounts.yml", "backstage", {"name" => "Backstage"}
+        USER_FIXTURES.each do |label, attributes|
+          append_backstage_fixture "test/fixtures/users.yml", label, attributes.merge("account" => "backstage")
+        end
+      end
+
+      # Appends a fixture under its label unless the label is already there,
+      # creating the file when it is missing.
+      def append_backstage_fixture(path, label, attributes)
+        entry = "#{label}:\n" + attributes.map { |key, value| "  #{key}: #{value}\n" }.join
+        return create_file(path, entry) unless backstage_file?(path)
+
+        content = File.read(File.join(destination_root, path))
+        return if content.match?(/^#{Regexp.escape(label)}:/)
+
+        separator = if content.empty?
+          ""
+        else
+          (content.end_with?("\n") ? "\n" : "\n\n")
+        end
+        append_to_file path, separator + entry
+      end
+
+      def backstage_file?(path)
+        File.exist?(File.join(destination_root, path))
+      end
+
+      def say_backstage_access
+        say "  - Backstage access: signed-in users listed in credentials (bin/rails credentials:edit)"
+        say "    backstage:"
+        say "      emails:"
+        say "        - you@example.com"
+        say "    Anyone else gets a 404. Do not set backstage.username or password: Solid Errors"
+        say "    turns its Basic Auth back on when a password is set."
+      end
+
+      def say_backstage_signin_pending
+        return if backstage_signin_pending.empty?
+
+        say ""
+        say "These files were changed by hand, so they keep their Basic Auth. Move them to", :yellow
+        say "the backstage sign-in yourself (BackstageController#require_backstage_access):"
+        backstage_signin_pending.uniq.each { |path| say "  - #{path}" }
+      end
+
+      def backstage_access_methods
+        <<-RUBY
+  # Who may open the backstage and use the admin-only MCP tools: an unblocked
+  # user whose email is listed in credentials (backstage.emails). An empty list
+  # is nobody. A list in config.x.backstage_emails is used instead, even an
+  # empty one; that is how the tests grant access. (Unset, config.x answers an
+  # empty OrderedOptions, not nil.)
+  def self.backstage_emails
+    emails = Rails.configuration.x.backstage_emails
+    emails = Rails.application.credentials.dig(:backstage, :emails) unless emails.is_a?(Array)
+    Array(emails).map { |email| email.to_s.strip.downcase }
+  end
+
+  def backstage_access?
+    !blocked? && self.class.backstage_emails.include?(email_address)
+  end
+
+        RUBY
+      end
+
+      def backstage_controller_header
+        <<-RUBY
+  # The app's sign-in rather than a shared Basic Auth password, for every
+  # backstage page: the overview, Security and, through base_controller_class,
+  # the Solid Errors and Mission Control Jobs engines. Who gets in is
+  # User#backstage_access?; anyone else gets a 404, so the pages never confirm
+  # they exist.
+  include Authentication
+
+  # After the include, so it runs behind require_authentication and can rely
+  # on Current.session being resolved.
+  before_action :require_backstage_access
+
+        RUBY
+      end
+
+      def backstage_controller_private
+        <<-RUBY
+
+  private
+
+  # ActiveRecord::RecordNotFound rather than a redirect with an alert: the
+  # alert would confirm there is a backstage.
+  def require_backstage_access
+    raise ActiveRecord::RecordNotFound unless Current.user&.backstage_access?
+  end
+
+  # Restated rather than inherited: this controller serves two mounted
+  # engines, and inside one a bare new_session_path generates against the
+  # engine's routes. main_app reaches the app's sign-in from anywhere.
+  #
+  # 303 for PATCH/PUT/DELETE: both engines submit those verbs (resolve, retry,
+  # discard), and Turbo keeps the verb through a 302, so an expired session on
+  # Discard would re-issue the DELETE against the sign-in page.
+  def request_authentication
+    session[:return_to_after_authenticating] = request.url
+    redirect_to main_app.new_session_path
+    response.status = :see_other if request.patch? || request.put? || request.delete?
+  end
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/maquina/backstage_signin/templates/test/integration/backstage_access_test.rb

@@ -0,0 +1,78 @@
+require "test_helper"
+require_relative "../test_helpers/session_test_helper"
+
+# The backstage is behind the app's sign-in (generated by the maquina dashboard
+# generators). Only a signed-in, unblocked user whose email is on the backstage
+# list gets in; anyone else signed in gets a 404, so the pages never confirm
+# they exist. The list lives in credentials (backstage.emails); these tests set
+# config.x.backstage_emails, which User.backstage_emails reads first.
+class BackstageAccessTest < ActionDispatch::IntegrationTest
+  # The engine pages mounted under the backstage prefix, whichever are installed.
+  PAGES = %w[errors jobs security].freeze
+
+  setup do
+    @emails_before = Rails.configuration.x.backstage_emails
+    Rails.configuration.x.backstage_emails = [users(:backstage_operator).email_address]
+  end
+
+  teardown do
+    Rails.configuration.x.backstage_emails = @emails_before
+  end
+
+  test "signed out, every backstage page asks to sign in" do
+    # Before any request: after one into a mounted engine, URL helpers in an
+    # integration test generate under that engine's mount point.
+    sign_in = new_session_url
+
+    backstage_paths.each do |path|
+      get path
+
+      assert_redirected_to sign_in, path
+    end
+  end
+
+  test "a user not on the list gets not found on every backstage page" do
+    sign_in_as users(:backstage_member)
+
+    backstage_paths.each do |path|
+      get path
+
+      assert_response :not_found, path
+    end
+  end
+
+  test "a blocked user on the list gets not found" do
+    users(:backstage_operator).block!(reason: "test")
+    sign_in_as users(:backstage_operator)
+
+    get backstage_dashboard_path
+
+    assert_response :not_found
+  end
+
+  test "an empty list lets nobody in" do
+    Rails.configuration.x.backstage_emails = []
+    sign_in_as users(:backstage_operator)
+
+    get backstage_dashboard_path
+
+    assert_response :not_found
+  end
+
+  test "a user on the list gets in" do
+    sign_in_as users(:backstage_operator)
+
+    get backstage_dashboard_path
+
+    assert_response :success
+  end
+
+  private
+
+  def backstage_paths
+    mounted = Rails.application.routes.routes.map { |route| route.path.spec.to_s }
+    pages = PAGES.map { |page| "#{backstage_dashboard_path}/#{page}" }.select { |path| mounted.any? { |spec| spec.start_with?(path) } }
+
+    [backstage_dashboard_path, *pages]
+  end
+end

data/lib/generators/maquina/csp_reports/csp_reports_generator.rb

@@ -1,10 +1,12 @@
 require "rails/generators"
 require "rails/generators/migration"
+require_relative "../mcp/mcp_sibling_tools"
 
 module Maquina
   module Generators
     class CspReportsGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
+      include McpSiblingTools
 
       source_root File.expand_path("templates", __dir__)
 
@@ -130,7 +132,12 @@ module Maquina
         end
       end
 
-      # 9. Post-install message
+      # 9. MCP tools (admin only, read-only), when maquina:mcp is installed
+      def create_mcp_tools
+        @mcp_tools_installed = install_mcp_tools(:csp_reports)
+      end
+
+      # 10. Post-install message
       def show_post_install
         return if options[:quiet]
 
@@ -141,6 +148,11 @@ module Maquina
         say "  - Add the table: bin/rails db:migrate (db:prepare on deploy)"
         say "  - Watch the Security page while the policy is report-only, then set"
         say "    content_security_policy_report_only = false to enforce it."
+        if @mcp_tools_installed
+          say ""
+          say "MCP tools (admin only, read-only): app/models/mcp/tools/csp_reports.rb", :green
+          say "  list_csp_reports, csp_report_summary"
+        end
         if @report_uri_pending
           say ""
           say "Point the policy at the endpoint in config/initializers/content_security_policy.rb:", :yellow

data/lib/generators/maquina/csp_reports/templates/app/models/mcp/tools/csp_reports.rb

@@ -0,0 +1,71 @@
+# MCP tools over the Content Security Policy violations browsers report
+# (generated by maquina:csp_reports).
+#
+# Admin only: a member's token neither sees nor reaches these tools. Read-only.
+# Reported URLs are stored without query or fragment; the reporter's IP address
+# is not returned.
+module Mcp
+  module Tools
+    module CspReports
+      ADMIN_ONLY = true
+      WRITE_TOOLS = %w[].freeze
+
+      MAX_LIMIT = 50
+      MAX_DAYS = 30
+      SCHEMA = "https://json-schema.org/draft/2020-12/schema"
+
+      DEFINITIONS = [
+        {
+          name: "list_csp_reports",
+          description: "Content Security Policy violations browsers reported, newest first. Each entry has " \
+            "the directive that was violated, the blocked URI, the page (document URI), the source file " \
+            "with line and column, the disposition (enforce or report), a code sample when the browser " \
+            "sent one, the user agent and at (ISO 8601 UTC). Reports are kept for 30 days. Returns at " \
+            "most 50 entries.",
+          inputSchema: {
+            "$schema": SCHEMA, type: "object",
+            properties: {limit: {type: "integer", description: "Number of reports to return, 1-50. Default 20."}},
+            required: [], additionalProperties: false
+          },
+          annotations: {readOnlyHint: true}
+        },
+        {
+          name: "csp_report_summary",
+          description: "Content Security Policy violations over the last days, grouped by directive, " \
+            "blocked URI and page, most frequent first: one group per thing to fix, with its count and " \
+            "last_seen (ISO 8601 UTC). Also returns the total number of reports in the window. Returns at " \
+            "most 50 groups.",
+          inputSchema: {
+            "$schema": SCHEMA, type: "object",
+            properties: {days: {type: "integer", description: "Window length in days, 1-30. Default 7."}},
+            required: [], additionalProperties: false
+          },
+          annotations: {readOnlyHint: true}
+        }
+      ].freeze
+
+      def self.list_csp_reports(scope:, limit: 20)
+        reports = ::Security::CspViolation.recent.limit(limit.to_i.clamp(1, MAX_LIMIT)).map do |violation|
+          {effective_directive: violation.effective_directive, blocked_uri: violation.blocked_uri,
+           document_uri: violation.document_uri, source_file: violation.source_file,
+           line_number: violation.line_number, column_number: violation.column_number,
+           disposition: violation.disposition, sample: violation.sample, user_agent: violation.user_agent,
+           at: violation.created_at.utc.iso8601}
+        end
+
+        {reports: reports}
+      end
+
+      def self.csp_report_summary(scope:, days: 7)
+        days = days.to_i.clamp(1, MAX_DAYS)
+        report = ::Security::CspViolationReport.new(window: days.days, limit: MAX_LIMIT)
+
+        groups = report.top.map do |group|
+          group.to_h.merge(last_seen: group.last_seen&.utc&.iso8601)
+        end
+
+        {days: days, total: report.total, groups: groups}
+      end
+    end
+  end
+end

data/lib/generators/maquina/csp_reports/templates/test/models/mcp/tools/csp_reports_test.rb

@@ -0,0 +1,35 @@
+require "test_helper"
+
+# The CSP report MCP tools are admin only (generated by maquina:csp_reports).
+# A member's token must not learn they exist: they are absent from tools/list
+# and a call gets the same -32602 as an unknown tool. McpTestHelper turns
+# any MCP feature flag on, so the role is the only gate tested.
+class Mcp::Tools::CspReportsTest < ActionDispatch::IntegrationTest
+  TOOLS = Mcp::Tools::CspReports::DEFINITIONS.map { |definition| definition[:name] }
+  ARGUMENTS = {}.freeze
+
+  test "an admin sees the tools" do
+    assert_equal TOOLS, TOOLS & listed_tools(users(:mcp_admin))
+  end
+
+  test "a member does not see the tools" do
+    assert_empty TOOLS & listed_tools(users(:mcp_member))
+  end
+
+  test "a member calling any of the tools gets unknown tool" do
+    token = oauth_token_for(users(:mcp_member), scope: "read write")
+
+    TOOLS.each do |name|
+      mcp_post({jsonrpc: "2.0", id: 1, method: "tools/call", params: {name: name, arguments: ARGUMENTS.fetch(name, {})}}, token: token)
+
+      assert_equal(-32602, response.parsed_body.dig("error", "code"), name)
+    end
+  end
+
+  private
+
+  def listed_tools(user)
+    mcp_post({jsonrpc: "2.0", id: 1, method: "tools/list", params: {}}, token: oauth_token_for(user, scope: "read write"))
+    response.parsed_body.dig("result", "tools").map { |tool| tool["name"] }
+  end
+end

data/lib/generators/maquina/mcp/USAGE

@@ -0,0 +1,37 @@
+Description:
+  Adds an MCP server at POST /mcp for protocol revision 2026-07-28, for
+  clients signed in through maquina:oauth. Needs maquina:oauth. Hand-rolled:
+  no mcp gem and no CORS gem in the app.
+
+  Stateless JSON-RPC: every request carries its protocol version in
+  params._meta and mirrors it, the method and the tool name in the
+  MCP-Protocol-Version, Mcp-Method and Mcp-Name headers. server/discover
+  answers without a token; tools/list and tools/call need a bearer token
+  issued for this server's /mcp. initialize gets a 404 naming 2026-07-28,
+  GET and DELETE get a 405. Tools that change data need the write scope
+  (403 insufficient_scope otherwise). Calls are rate limited per token.
+
+  Installs McpController, the McpAuthenticatable concern, a CORS middleware
+  (config/initializers/mcp_cors.rb), the tool registry in app/models/mcp/
+  (Tools, ToolDefinitions, ToolError, UserScope) and app/models/mcp/tools/app.rb
+  with a whoami tool, written only if missing. Tools reach the token's own
+  user's data through Mcp::UserScope. If solid_errors, solid_queue, security
+  or csp_reports are already installed, their admin-only MCP tools are added
+  too. Admin-only tools are for users on the backstage list (backstage.emails
+  in credentials, User#backstage_access?, added to app/models/user.rb); an
+  account's admin role is not enough. Generates a test helper (mcp_post, oauth_token_for), an end-to-end
+  flow test, a protocol conformance test and a registry test. Anything it
+  cannot place safely is listed after the install.
+
+Options:
+  --flag NAME     Gate MCP behind a feature flag: rewrites Mcp::FLAG = nil in
+                  app/models/mcp.rb and adds flag-off tests
+  --prefix PATH   Where maquina:oauth put Connected apps (default /settings)
+  --skip-views    maquina:oauth ran with --skip-views; the flow test skips its pages
+  --quiet         Suppress post-install instructions
+
+Examples:
+  rails g maquina:oauth && rails g maquina:mcp
+  rails g maquina:mcp --flag beta_mcp
+
+  Then: npx @modelcontextprotocol/inspector, connect to http://localhost:3000/mcp