karst 0.2.0 → 0.4.0

data/lib/karst/web/panel.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require "cgi"
+require "json"
 require "rack/utils"
 require "active_support"
 require "active_support/number_helper"
 require "base64"
 require "digest"
+require_relative "../access/outcome_groups"
 
 module Karst
   module Web
@@ -99,6 +101,21 @@ module Karst
         .ordinary-sample h2{margin:0 0 .45rem}
         .ordinary-sample details{margin:.55rem 0}
         .write-warning{border:2px solid #b3261e;border-radius:.4rem;padding:.7rem .85rem;background:#fff7f6}
+        section.reproduce textarea{font:13px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;padding:.4rem .5rem;border:1px solid #ccc;border-radius:.3rem;width:100%;min-height:5rem;resize:vertical}
+        section.reproduce form{display:grid;gap:.75rem;margin:.6rem 0}
+        section.reproduce .row{display:flex;gap:.75rem;flex-wrap:wrap}
+        section.reproduce label{flex:1 1 10rem}
+        section.reproduce label input{width:100%}
+        .recipe{border:1px solid #ddd;border-radius:.5rem;padding:.9rem 1rem;margin:.9rem 0}
+        .recipe h3{font-size:.95rem;margin:.9rem 0 .3rem}
+        .recipe h3:first-child{margin-top:0}
+        .recipe p{margin:.2rem 0}
+        .recipe pre{overflow-x:auto;background:#f6f6f7;border:1px solid #e2e2e2;border-radius:.4rem;padding:.7rem .8rem;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;margin:.3rem 0 0}
+        .recipe dl{display:grid;grid-template-columns:auto 1fr;gap:.15rem .75rem;margin:.2rem 0;font-size:.9rem}
+        .recipe dt{font-weight:600;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+        .recipe dd{margin:0;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;overflow-wrap:anywhere}
+        .redacted{color:#8a5b00;font-weight:600}
+        .unobserved{color:#666;font-size:.88rem}
         small{color:#666}
         .sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}
         @media (max-width:480px){
@@ -126,6 +143,11 @@ module Karst
           .hint{color:#d8a63d}
           .failed,.pending{border-left-color:#e5534b}
           .write-warning{background:#321b1a}
+          section.reproduce textarea{background:#1f2023;border-color:#3a3b3e;color:#e4e4e6}
+          .recipe{border-color:#33343a}
+          .recipe pre{background:#1f2023;border-color:#2c2d31}
+          .redacted{color:#d8a63d}
+          .unobserved{color:#9a9aa0}
         }
       CSS
       private_constant :STYLE
@@ -143,16 +165,24 @@ module Karst
 
       # rubocop:disable Metrics/ClassLength
       class << self
+        # `identity_snapshot` is the request's one Karst::Identity::Snapshot;
+        # every identity-configuration question this page asks (principal
+        # sources, setup readiness, browser Test As support) reads it, never
+        # the live configuration, so rendering N users never resolves
+        # configuration N times. Taken here when the caller has none.
         # rubocop:disable Metrics/ParameterLists
         def render(params: {}, access_result: nil, csrf_token: nil, browser_identity_active: false,
                    route_lookup_limitation: nil, unapproved_candidates: [], population_approval_error: nil,
-                   principal_source_selection_saved: false, principal_source_selection_error: nil)
+                   principal_source_selection_saved: false, principal_source_selection_error: nil,
+                   reproduction: nil, identity_snapshot: nil)
           state = { csrf_token: csrf_token, browser_identity_active: browser_identity_active,
+                    identity: identity_snapshot || Identity.snapshot,
                     route_lookup_limitation: route_lookup_limitation,
                     unapproved_candidates: unapproved_candidates,
                     population_approval_error: population_approval_error,
                     principal_source_selection_saved: principal_source_selection_saved,
-                    principal_source_selection_error: principal_source_selection_error }
+                    principal_source_selection_error: principal_source_selection_error,
+                    reproduction: reproduction }
           [200, HEADERS.dup, [document(params, access_result, state)]]
         end
         # rubocop:enable Metrics/ParameterLists
@@ -177,9 +207,10 @@ module Karst
           action = string_param(params, "action")
           http_method = string_param(params, "method")
           path = string_param(params, "path")
-          "#{testing_banner(path, state[:csrf_token], state[:browser_identity_active])}" \
+          "#{testing_banner(path, state)}" \
             "#{route_header(http_method, path, state[:route_lookup_limitation])}" \
-            "#{access_section(http_method, path, controller, action, access_result, state)}"
+            "#{access_section(http_method, path, controller, action, access_result, state)}" \
+            "#{reproduction_section(params, http_method, path, state)}"
         end
 
         def string_param(params, key)
@@ -189,8 +220,9 @@ module Karst
 
         # -- Testing-as banner ------------------------------------------------
 
-        def testing_banner(path, csrf_token, active)
-          return "" unless active && Identity.browser_supported? && csrf_token
+        def testing_banner(path, state)
+          csrf_token = state[:csrf_token]
+          return "" unless state[:browser_identity_active] && state[:identity].browser_supported? && csrf_token
 
           fields = hidden("operation", "stop_test_as") + hidden("csrf_token", csrf_token) + hidden("path", path)
           <<~HTML
@@ -239,7 +271,7 @@ module Karst
 
         # -- Primary action: access analysis ------------------------------------
 
-        # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
         def access_section(http_method, path, controller, action, result, state)
           return setup_notice_section(state) if path.empty? || state[:route_lookup_limitation]
 
@@ -248,12 +280,14 @@ module Karst
           body = if http_method == "GET"
                    analyze_form(context, state)
                  else
-                   "<p>Access analysis is available for GET routes only.</p>"
+                   "<p>Access analysis is available for GET routes only. " \
+                     "Use <strong>Reproduce request</strong> below to issue this one request " \
+                     "and get a recipe for it.</p>"
                  end
           heading = "<h2 class=\"sr-only\">Access analysis</h2>"
           "<section class=\"access\">#{heading}#{body}#{access_result(result, state)}</section>"
         end
-        # rubocop:enable Metrics/ParameterLists
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
         # A developer with several Devise models (or no automatic
         # authentication integration at all) needs to know that before
@@ -269,17 +303,16 @@ module Karst
         # away must still say so, rather than have the confirmation vanish
         # the moment `sources` becomes truthy.
         def setup_notice_section(state)
-          sources = principal_sources
+          sources = state[:identity].principal_sources
           notice = principal_source_selection_notice(state)
           return notice if sources
 
           heading = "<h2 class=\"sr-only\">Access analysis</h2>"
-          body = "#{notice}#{principal_source_hint(sources)}"
+          body = "#{notice}#{principal_source_hint(state[:identity])}"
           "<section class=\"access\">#{heading}#{body}</section>"
         end
 
         def analyze_form(context, state)
-          sources = principal_sources
           label = "Who can use this? (test #{Karst.config.access_sweep_limit} users)"
           operation = "<input type=\"hidden\" name=\"operation\" value=\"access_sweep\">"
           button = "<button class=\"primary\" type=\"submit\">#{escape(label)}</button>"
@@ -289,19 +322,13 @@ module Karst
           # `sources` truthy must still tell the developer it worked, rather
           # than have the confirmation vanish the moment it stops being
           # needed.
-          "#{principal_source_selection_notice(state)}#{form}#{principal_source_hint(sources)}"
-        end
-
-        def principal_sources
-          Identity.principal_sources
-        rescue Identity::Error
-          nil
+          "#{principal_source_selection_notice(state)}#{form}#{principal_source_hint(state[:identity])}"
         end
 
-        def principal_source_hint(sources)
-          return "" if sources
+        def principal_source_hint(identity)
+          return "" if identity.principal_sources
 
-          setup = Identity.setup_state
+          setup = identity.setup_state
           return principal_source_selection_form(setup) if setup.status == :ambiguous
 
           custom_auth_hint
@@ -368,6 +395,206 @@ module Karst
           "<input type=\"hidden\" name=\"#{name}\" value=\"#{escape(value)}\">"
         end
 
+        # -- Request reproduction -----------------------------------------------
+
+        # The one place /karst answers "something calls this endpoint -- what
+        # request do I send to exercise the same behavior?". Deliberately a
+        # collapsed <details> below the access analysis rather than a peer of
+        # it: reproduction issues a real request with real non-database side
+        # effects, so it is something a developer opens on purpose, never
+        # something the page does on arrival. Everything below renders the
+        # same evidence document Karst::CLI::Reproduction hands the MCP tool
+        # and the CLI, so the panel cannot show a recipe those two would not.
+        def reproduction_section(params, http_method, path, state)
+          document = state[:reproduction]
+          return "" if path.empty? && document.nil?
+          return "" unless state[:csrf_token]
+
+          open = document ? " open" : ""
+          "<section class=\"reproduce\"><details#{open}><summary><strong>Reproduce request</strong></summary>" \
+            "#{reproduction_intro}#{reproduction_form(params, http_method, path, state)}" \
+            "#{reproduction_result(document)}</details></section>"
+        end
+
+        def reproduction_intro
+          "<p class=\"meta\">Karst issues this request once against your running application and shows what " \
+            "actually happened, plus a cURL command for exactly what it sent. Database writes are rolled " \
+            "back on the same connection; jobs, mail, outbound HTTP, files, and other connections are not. " \
+            "Secrets are replaced by placeholders, so a generated command may need a credential filled in.</p>"
+        end
+
+        def reproduction_form(params, http_method, path, state)
+          <<~HTML
+            <form action="/karst" method="post">
+            #{hidden('operation', 'reproduce_request')}#{hidden('csrf_token', state[:csrf_token])}
+            #{hidden('controller', string_param(params, 'controller'))}#{hidden('action', string_param(params, 'action'))}
+            <div class="row">
+            <label>Method <input name="method" value="#{escape(http_method.empty? ? 'GET' : http_method)}" required></label>
+            <label>Path <input name="path" value="#{escape(path)}" required></label>
+            </div>
+            <div class="row">
+            <label>Content type <input name="content_type" value="#{escape(string_param(params, 'content_type'))}" placeholder="application/json"></label>
+            </div>
+            <label>Body <textarea name="body" placeholder='{"serial_number": "ABC123"}'>#{escape(string_param(params, 'body'))}</textarea></label>
+            <label>Headers <small>one per line, as <code>Name: value</code></small>
+            <textarea name="headers" placeholder="Authorization: Bearer ...">#{escape(string_param(params, 'headers'))}</textarea></label>
+            <div><button class="primary" type="submit">Send once and build request</button></div>
+            </form>
+          HTML
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def reproduction_result(document)
+          return "" unless document
+          return "<p class=\"hint\" role=\"alert\">#{escape(document[:error][:message])}</p>" if document[:error]
+
+          sections = [recipe_request(document[:request]), recipe_identity(document[:identity]),
+                      recipe_execution(document[:execution]), recipe_response(document[:response]),
+                      recipe_effects(document[:execution], document[:isolation]),
+                      recipe_unobserved(document[:unobserved]), recipe_curl(document[:reproduce][:curl])]
+          "<div class=\"recipe\">#{sections.join}</div>"
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def recipe_request(request)
+          "<h3>Request</h3><p class=\"route-path\">#{escape(request[:method])} #{escape(request[:path])}</p>" \
+            "#{recipe_pairs('Route parameters', request[:route_params])}" \
+            "#{recipe_pairs('Query parameters', request[:query_params])}" \
+            "#{recipe_pairs('Headers', request[:headers])}" \
+            "#{recipe_body(request)}"
+        end
+
+        def recipe_body(request)
+          return "" unless request[:body]
+          if request[:body_format] == "opaque"
+            return "<h3>Body</h3><p class=\"unobserved\">Karst sent a body it could not parse as JSON or " \
+                   "form data, so it is not shown.</p>"
+          end
+
+          "<h3>Body <small>(#{escape(request[:body_format])})</small></h3>" \
+            "<pre>#{escape(JSON.pretty_generate(request[:body]))}</pre>"
+        end
+
+        # Redacted values are visibly marked rather than silently mixed in
+        # with observed ones, so a developer copying a value out of this
+        # panel can always tell which is which.
+        def recipe_pairs(title, pairs)
+          return "" if pairs.nil? || pairs.empty?
+
+          rows = pairs.map do |name, value|
+            "<dt>#{escape(name)}</dt><dd>#{recipe_value(value)}</dd>"
+          end.join
+          "<h3>#{escape(title)}</h3><dl>#{rows}</dl>"
+        end
+
+        def recipe_value(value)
+          text = value.is_a?(String) ? value : JSON.generate(value)
+          return "<span class=\"redacted\">#{escape(text)}</span>" if placeholder?(text)
+
+          escape(text)
+        end
+
+        def placeholder?(text)
+          text.start_with?("<") && text.end_with?(">")
+        end
+
+        # The same requested/observed/confirmation evidence verify_access
+        # reports, never a bare echo of the identity Karst assumed: a
+        # mismatch, an absence, or an unobservable outcome stays visible here
+        # exactly as it would in a "sent as User X" claim it is not entitled
+        # to make.
+        def recipe_identity(identity)
+          html = "<h3>Identity</h3><p>#{escape(identity_confirmation_label(identity))}</p>"
+          html += "<p class=\"unobserved\">#{escape(identity[:reason])}</p>" if identity[:reason]
+          html += identity_failure_detail(identity)
+          "#{html}<p class=\"unobserved\">Karst assumed this identity directly; it did not exercise how an " \
+            "external client would authenticate this endpoint.</p>"
+        end
+
+        def identity_confirmation_label(identity)
+          requested = principal_summary(identity[:requested], "anonymous")
+          observed = principal_summary(identity[:observed], "no principal")
+          case identity[:confirmation]
+          when "confirmed" then "observed #{observed} (identity confirmed)"
+          when "confirmed_anonymous" then "observed no principal (anonymous confirmed)"
+          when "absent" then "requested #{requested}, observed no principal (NOT confirmed)"
+          when "mismatch" then "requested #{requested}, observed #{observed} (MISMATCH)"
+          when "contaminated" then "anonymous probe observed #{observed} (CONTAMINATED)"
+          else "identity unobservable#{": #{identity[:observation_error]}" if identity[:observation_error]}"
+          end
+        end
+
+        def principal_summary(value, absent_label)
+          value ? "#{value[:model]} ##{value[:id]}" : absent_label
+        end
+
+        def identity_failure_detail(identity)
+          detail = []
+          detail << "Identity setup: #{escape(identity[:establishment_error])}" if identity[:establishment_error]
+          detail << "Cleanup: #{escape(identity[:cleanup_error])}" if identity[:cleanup_error]
+          detail.map { |line| "<p class=\"unobserved\">#{line}</p>" }.join
+        end
+
+        def recipe_execution(execution)
+          dispatched = if execution[:controller]
+                         "#{escape(execution[:controller])}##{escape(execution[:action])}"
+                       else
+                         "<span class=\"unobserved\">no controller dispatched</span>"
+                       end
+          "<h3>Observed execution</h3><p>#{dispatched}</p>#{recipe_controller_completed(execution)}" \
+            "#{recipe_execution_detail(execution)}#{recipe_rendered(execution[:rendered])}"
+        end
+
+        def recipe_execution_detail(execution)
+          halted = execution[:halted_callback]
+          exception = execution[:exception_class]
+          "#{"<p>Halted at #{escape(halted)}</p>" if halted}" \
+            "#{"<p>Exception: #{escape(exception)} (during #{escape(execution[:exception_phase])})</p>" if exception}"
+        end
+
+        def recipe_controller_completed(execution)
+          completed = execution[:controller_completed]
+          return "" if completed.nil?
+
+          "<p class=\"meta\">Controller completed: #{completed}</p>"
+        end
+
+        def recipe_rendered(rendered)
+          return "" if rendered.nil? || rendered.empty?
+
+          items = rendered.map do |template|
+            state = template[:completed] ? "" : " <span class=\"unobserved\">(raised)</span>"
+            "<li>#{escape(template[:virtual_path])}#{state}</li>"
+          end.join
+          "<p>Rendered:</p><ul>#{items}</ul>"
+        end
+
+        def recipe_response(response)
+          return "<h3>Observed response</h3><p class=\"unobserved\">No response observed.</p>" unless response[:status]
+
+          type = response[:content_type]
+          redirect = response[:redirect]
+          "<h3>Observed response</h3><p>#{status_title(response[:status])}" \
+            "#{" · #{escape(type)}" if type}#{" → #{escape(redirect)}" if redirect}</p>"
+        end
+
+        def recipe_effects(execution, isolation)
+          count = execution[:write_count]
+          "<h3>Observed effects</h3><p>#{escape(count)} database #{count == 1 ? 'write' : 'writes'} " \
+            "· rollback attempted on the same connection</p>" \
+            "<p class=\"unobserved\">Not isolated: #{escape(isolation[:not_isolated].join(', '))}.</p>"
+        end
+
+        def recipe_unobserved(unobserved)
+          return "" if unobserved.nil? || unobserved.empty?
+
+          "<h3>Not observed</h3><p class=\"unobserved\">#{escape(unobserved.join(', '))}</p>"
+        end
+
+        def recipe_curl(curl)
+          "<h3>Reproduce</h3><pre><code>#{escape(curl)}</code></pre>"
+        end
+
         def access_result(result, state)
           return "" unless result
           return "<p>Analysis unavailable: #{escape(result.message)}</p>" if result.is_a?(StandardError)
@@ -379,13 +606,17 @@ module Karst
         # any automatic candidate-population retries as a single answer, so
         # a usable user found through a population reads exactly like one
         # found in the sample -- there is no second workflow to enter.
+        #
+        # Test As is offered per user, so whether it is available at all is
+        # decided once here: `test_as_token` is the CSRF token only when the
+        # snapshot says browser identity is supported, and nil otherwise.
         def search_result(result, state)
-          csrf_token = state[:csrf_token]
+          test_as_token = state[:csrf_token] if state[:identity].browser_supported?
           outcomes = result.all_outcomes
           usable = outcomes.select { |outcome| usable_outcome?(outcome) }
           write_count = outcomes.count(&:writes_observed)
-          "#{usable_outcomes(usable, result, state)}#{ordinary_sample(result, csrf_token)}" \
-            "#{populations_section(result, csrf_token)}#{write_evidence(write_count)}#{search_meta(result)}"
+          "#{usable_outcomes(usable, result, state, test_as_token)}#{ordinary_sample(result, nil)}" \
+            "#{populations_section(result, test_as_token)}#{write_evidence(write_count)}#{search_meta(result)}"
         end
 
         # -- Automatic candidate-population retries ----------------------------
@@ -496,17 +727,15 @@ module Karst
 
         # -- Usable principals ---------------------------------------------------
 
-        def usable_outcomes(outcomes, result, state)
-          csrf_token = state[:csrf_token]
+        def usable_outcomes(outcomes, result, state, test_as_token)
           body = if outcomes.empty?
                    candidate_review(state, result)
                  else
-                   usable_cards(outcomes,
-                                result, csrf_token)
+                   usable_cards(outcomes, result, test_as_token)
                  end
           heading = outcomes.empty? ? "No verified usable user found" : "Verified usable user"
           "<section class=\"usable\"><h2>#{heading}</h2>" \
-            "#{test_as_hint(outcomes, csrf_token)}#{body}</section>"
+            "#{test_as_hint(outcomes, state, test_as_token)}#{body}</section>"
         end
 
         # The one place /karst mentions candidate groups at all: a small
@@ -547,11 +776,11 @@ module Karst
           outcomes.map { |outcome| usable_principal(outcome, result, csrf_token) }.join
         end
 
-        def test_as_hint(outcomes, csrf_token)
-          return "" if outcomes.empty? || (Identity.browser_supported? && csrf_token)
+        def test_as_hint(outcomes, state, test_as_token)
+          return "" if outcomes.empty? || test_as_token
 
-          state = Identity.setup_state
-          return "<p class=\"hint\">#{escape(state.message)}</p>" if state.status == :ambiguous
+          setup = state[:identity].setup_state
+          return "<p class=\"hint\">#{escape(setup.message)}</p>" if setup.status == :ambiguous
 
           custom_auth_hint
         end
@@ -561,7 +790,33 @@ module Karst
           action = test_as_form(outcome.principal, result.path, csrf_token)
           "<article class=\"usable-principal\"><h4><span>#{principal_label(outcome.principal)}#{writes}</span>" \
             "#{action}</h4><p>#{outcome_title(outcome, prefix: 'Observed ')} · " \
-            "#{escape(outcome.elapsed_ms)}ms</p>#{sampled_for(outcome)}</article>"
+            "#{escape(outcome.elapsed_ms)}ms</p>#{identity_note(outcome)}#{sampled_for(outcome)}</article>"
+        end
+
+        # Karst asking the application to run as a principal is not evidence
+        # that it did. Silence here means the application itself resolved
+        # exactly the requested principal while running this request;
+        # anything else says so out loud, because "this user reached the
+        # page" would otherwise be a claim Karst cannot support.
+        def identity_note(outcome)
+          evidence = outcome.identity
+          return "" if evidence.nil? || evidence.confirmation == :confirmed
+
+          "<p class=\"meta\">⚠ #{escape(identity_summary(evidence))}</p>"
+        end
+
+        def identity_summary(evidence)
+          case evidence.confirmation
+          when :confirmed_anonymous then "Ran anonymously: the application observed no principal."
+          when :absent then "The application observed no principal for this request — it did not run as this user."
+          when :mismatch then "The application observed #{observed_label(evidence)}, not the requested user."
+          when :contaminated then "Anonymous probe contaminated: the application observed #{observed_label(evidence)}."
+          else "Identity not runtime-confirmed: #{evidence.observation_error}"
+          end
+        end
+
+        def observed_label(evidence)
+          evidence.observed ? "#{evidence.observed.model_name} ##{evidence.observed.id}" : "no principal"
         end
 
         # A compact, secondary line below the observed outcome, never a card
@@ -577,22 +832,19 @@ module Karst
 
         # -- Other observed outcomes (collapsed) ---------------------------------
 
+        # Semantic outcome groups, largest first -- the same grouping the CLI
+        # and MCP evidence use (see Karst::Access::OutcomeGroups).
         def observed_groups(outcomes, path, csrf_token)
-          outcomes.group_by { |item| outcome_group_key(item) }
-                  .map { |_key, grouped| outcome_group(grouped, path, csrf_token) }.join
-        end
-
-        def outcome_group_key(item)
-          [item.status, item.redirect, item.exception_class, item.halted_callback,
-           item.writes_observed, item.write_count]
+          Access::OutcomeGroups.group(outcomes).map { |group| outcome_group(group, path, csrf_token) }.join
         end
 
-        def outcome_group(outcomes, path, csrf_token)
-          first = outcomes.first
+        def outcome_group(group, path, csrf_token)
+          outcomes = group.outcomes
+          first = group.representative
           title = outcome_title(first)
           labels = outcomes.map { |item| outcome_principal(item, path, csrf_token) }.join
           halt = halted_callback(first)
-          usability = usable_outcome?(first) ? "Verified usable" : "Not verified as usable"
+          usability = group.usable ? "Verified usable" : "Not verified as usable"
           "<details><summary>#{title}#{halt_summary(first)} — #{outcomes.size}</summary>" \
             "#{halt}<p>#{usability}</p><ul>#{labels}</ul></details>"
         end
@@ -621,11 +873,14 @@ module Karst
         def outcome_principal(item, path, csrf_token)
           writes = item.writes_observed ? " — ⚠ #{escape(item.write_count)} database writes observed" : ""
           action = test_as_form(item.principal, path, csrf_token)
-          "<li>#{principal_label(item.principal)} — #{escape(item.elapsed_ms)}ms#{writes}#{action}</li>"
+          "<li>#{principal_label(item.principal)} — #{escape(item.elapsed_ms)}ms#{writes}" \
+            "#{identity_note(item)}#{action}</li>"
         end
 
+        # `csrf_token` is the search's test-as token: nil whenever browser
+        # identity is unsupported (see #search_result).
         def test_as_form(principal, path, csrf_token)
-          return "" unless Identity.browser_supported? && csrf_token
+          return "" unless csrf_token
 
           fields = hidden("operation", "test_as") + hidden("csrf_token", csrf_token) + hidden("path", path) +
                    hidden("principal_type", principal.model_name) + hidden("principal_id", principal.id)

data/lib/karst.rb

@@ -24,6 +24,8 @@ require_relative "karst/access/population_approval"
 require_relative "karst/access/approved_populations"
 require_relative "karst/access/principal_source_selection"
 require_relative "karst/access/selected_principal_sources"
+require_relative "karst/reproduction/exercise"
+require_relative "karst/reproduction/curl"
 
 # Public entry point for Karst configuration.
 module Karst

data/lib/rails/commands/karst/mcp/mcp_command.rb

@@ -2,6 +2,8 @@
 
 require "rails/command"
 require_relative "../boot"
+require "karst/mcp/compatibility"
+require "karst/version"
 
 module Rails
   module Command
@@ -25,14 +27,39 @@ module Rails
 
         def load_mcp!
           begin
-            gem "mcp", "~> 0.9.0"
+            gem "mcp", *::Karst::Mcp::Compatibility::REQUIREMENTS
           rescue Gem::LoadError
-            abort "Karst MCP requires the optional dependency. " \
-                  'Add gem "mcp", "~> 0.9.0" to your Gemfile and run bundle install.'
+            abort mcp_unavailable_message
           end
 
           require "karst/mcp/server"
         end
+
+        # "Not installed" and "installed at a version Karst does not support"
+        # need different fixes, so they get different messages: telling an
+        # application that already has mcp in its bundle to add it would
+        # send its developer looking for a problem they don't have.
+        def mcp_unavailable_message
+          requirement = ::Karst::Mcp::Compatibility.gemfile_requirement
+          installed = installed_mcp_version
+          if installed
+            "Karst MCP found mcp #{installed}, but Karst #{::Karst::VERSION} " \
+              "requires mcp #{requirement}. Constrain it in your Gemfile with " \
+              "gem \"mcp\", #{requirement} and run bundle update mcp."
+          else
+            "Karst MCP requires the optional dependency. " \
+              "Add gem \"mcp\", #{requirement} to your Gemfile and run bundle install."
+          end
+        end
+
+        # The mcp version this process can see but could not activate, if
+        # any. Bundler marks every gem in the bundle as loaded, so under
+        # `bin/rails` this is the version the bundle resolved; outside
+        # Bundler, it is the newest one installed.
+        def installed_mcp_version
+          spec = Gem.loaded_specs["mcp"] || Gem::Specification.find_all_by_name("mcp").max_by(&:version)
+          spec&.version
+        end
       end
     end
   end

data/lib/rails/commands/karst/reproduce/reproduce_command.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "rails/command"
+require "karst/cli/reproduction"
+require_relative "../boot"
+
+module Rails
+  module Command
+    module Karst
+      # Rails command entry point for the shared Reproduction adapter.
+      class ReproduceCommand < Base
+        include Karst::Boot
+
+        class_option :json, type: :boolean, default: false, desc: "Emit stable JSON evidence"
+        class_option :body, type: :string, desc: "Request body to send"
+        class_option :content_type, type: :string, desc: "Content type of --body (required with --body)"
+        class_option :header, type: :array, default: [], desc: "Request header, as 'Name: value' (repeatable)"
+        class_option :anonymous, type: :boolean, default: false,
+                                 desc: "Send without assuming any application identity"
+        class_option :as, type: :string,
+                          desc: "Send as one specific existing principal instead of the ordinary sampled " \
+                                "one, e.g. --as User:72. Resolved only through Karst's own configured " \
+                                "principal source(s); cannot be combined with --anonymous"
+        class_option :base_url, type: :string, desc: "Base URL for the generated cURL command"
+
+        desc "Issue one local request and print a reproducible, redacted recipe for it"
+        def perform(*arguments)
+          method, path = parse(arguments)
+          boot_karst_application!
+          exit(reproduction(method, path).call)
+        rescue ArgumentError => e
+          document = { schema_version: ::Karst::CLI::Reproduction::SCHEMA_VERSION,
+                       error: { type: "input_error", message: e.message } }
+          puts(options[:json] ? JSON.generate(document) : "Karst cannot reproduce this request:\n#{e.message}")
+          exit(2)
+        end
+
+        private
+
+        def reproduction(method, path)
+          ::Karst::CLI::Reproduction.new(
+            path: path, http_method: method, body: options[:body], content_type: options[:content_type],
+            headers: headers, anonymous: options[:anonymous], as: options[:as],
+            base_url: options[:base_url], json: options[:json]
+          )
+        end
+
+        def headers
+          Array(options[:header]).each_with_object({}) do |entry, result|
+            name, value = entry.to_s.split(":", 2)
+            raise ArgumentError, "expected --header 'Name: value'" if value.nil?
+
+            result[name.strip] = value.strip
+          end
+        end
+
+        def parse(arguments)
+          raise ArgumentError, "a local application path is required" if arguments.empty?
+          return ["GET", arguments.first] if arguments.size == 1
+          raise ArgumentError, "expected METHOD PATH" unless arguments.size == 2
+
+          arguments
+        end
+      end
+    end
+  end
+end