karst 0.1.0 → 0.4.0

data/lib/karst/web/panel.rb

@@ -1,10 +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
@@ -80,13 +83,9 @@ module Karst
         .usable-principal button[type=submit]{background:#0f5132;border-color:#0f5132;color:#fff;font-weight:600}
         .usable-principal button[type=submit]:hover{background:#0a3d25}
         .usable-principal p{margin:.5rem 0 0;color:#444;font-size:.92rem}
-        .related-state{margin:.75rem 0 0;padding:.6rem .75rem;border-left:3px solid #ccc;background:#fafafa;font-size:.9rem}
-        .related-state ul{margin:.25rem 0 0;padding-left:1.1rem}
         details{border:1px solid #e2e2e2;border-radius:.4rem;padding:.6rem .8rem;margin:.75rem 0}
         details summary{cursor:pointer;font-weight:600}
         details[open]>summary{margin-bottom:.5rem}
-        .scenario{border:1px solid #ddd;border-radius:.4rem;padding:.75rem;margin:.6rem 0}
-        .scenario h4{margin:.1rem 0}
         .evidence{display:flex;gap:1rem;flex-wrap:wrap;font-size:.9rem}
         .label{font-size:.72rem;font-weight:700;text-transform:uppercase;color:#666}
         .failed,.pending{border-left:4px solid #b3261e}
@@ -97,10 +96,26 @@ module Karst
         .population-attempt.hit .name{color:#0f5132}
         .population-attempt.untried{color:#777}
         .candidate-review{font-size:.9rem;color:#444;margin:.5rem 0 0}
+        .candidate-review label{display:flex;flex-direction:row;align-items:center;font-size:.9rem;margin:.35rem 0}
         .ordinary-sample{border:1px solid #ddd;border-radius:.5rem;padding:.8rem 1rem;margin:1rem 0}
         .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){
@@ -123,13 +138,16 @@ module Karst
           .population-attempt.hit .name{color:#7fd8a4}
           .population-attempt.untried{color:#8a8a90}
           .usable-principal button[type=submit]{background:#2e7d52;border-color:#2e7d52;color:#0b1a12}
-          .related-state{background:#1c1d20;border-color:#3a3b3e}
           details{border-color:#2c2d31}
-          .scenario{border-color:#33343a}
           .testing-banner{background:#3a2f0d;border-color:#6b5423;color:#f0e4c0}
           .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
@@ -147,15 +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_candidate_count: nil,
-                   principal_source_selection_saved: false, principal_source_selection_error: nil)
+                   route_lookup_limitation: nil, unapproved_candidates: [], population_approval_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_candidate_count: unapproved_candidate_count,
+                    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
@@ -180,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)
@@ -192,15 +220,15 @@ 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
             <div class="testing-banner" role="status">
-            <p><strong>Currently testing as an assumed browser identity.</strong></p>
-            <p><small>Stopping clears to whatever identity your configured clear_browser_identity hook defines
-            (commonly signed out) -- Karst does not restore a previous session.</small></p>
+            <p><strong>Currently testing as an assumed user.</strong></p>
+            <p><small>Stopping signs this browser out; Karst does not restore your previous session.</small></p>
             <form action="/karst" method="post">#{fields}<button type="submit">Stop testing as</button></form>
             </div>
           HTML
@@ -243,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]
 
@@ -252,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
@@ -273,19 +303,17 @@ 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
-          kind = sources && any_representative?(sources) ? "representative " : ""
-          label = "Who can use this? (test #{Karst.config.access_sweep_limit} #{kind}users)"
+          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>"
           form = "<form action=\"/karst\" method=\"post\">#{context}#{operation}#{button}</form>"
@@ -294,27 +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
-
-        # Only ever type-checks each configured source's evaluated records
-        # (see Access::PrincipalSampler.representative_capable?); it never
-        # queries or enumerates any of them, so this is safe to compute on
-        # every panel render.
-        def principal_sources
-          Identity.principal_sources
-        rescue Identity::Error
-          nil
-        end
-
-        def any_representative?(sources)
-          sources.values.any? { |source| Access::PrincipalSampler.representative_capable?(source.evaluate) }
+          "#{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
@@ -381,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)
@@ -392,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 ----------------------------
@@ -406,8 +624,8 @@ module Karst
         # Every approved population appears here, including the ones
         # deliberately not run -- "not tried" is reported honestly rather
         # than left to look like a failure. Only configured populations ever
-        # reach this list; a name merely discovered at /karst/populations is
-        # never executed automatically.
+        # reach this list; a name merely discovered after a failed analysis
+        # is never executed automatically.
         def populations_section(result, csrf_token)
           return "" if result.attempts.empty?
 
@@ -454,14 +672,6 @@ module Karst
           "could not be resolved#{detail}"
         end
 
-        def dominant_halted_callback(outcomes)
-          tally = Hash.new(0)
-          outcomes.filter_map(&:halted_callback).each { |callback| tally[callback] += 1 }
-          return nil if tally.empty?
-
-          tally.max_by { |_callback, count| count }.first
-        end
-
         def users(count)
           count == 1 ? "user" : "users"
         end
@@ -470,7 +680,7 @@ module Karst
           initial = result.initial.outcomes.size
           population = result.population_request_count
           total = initial + population
-          "<p class=\"meta\"><strong>Request accounting:</strong> #{escape(initial)} initial · " \
+          "<p class=\"meta\"><strong>Tested:</strong> #{escape(initial)} initial · " \
             "#{escape(population)} candidate population · #{escape(total)} total " \
             "#{users(total)}/requests · #{escape(total_seconds(result))}s elapsed.</p>"
         end
@@ -501,16 +711,6 @@ module Karst
           " from up to #{escape(size)} recent users"
         end
 
-        # A bounded candidate pool is reported explicitly rather than left
-        # implicit, so this never reads as "every user was searched."
-        def candidate_pool_note(result)
-          size = result.candidate_pool_size
-          return "" unless size
-
-          delimited = ActiveSupport::NumberHelper.number_to_delimited(size)
-          " · candidate pool: up to #{escape(delimited)} most recent users"
-        end
-
         def write_evidence(count)
           return "<p class=\"meta\">Database writes observed: 0</p>" if count.zero?
 
@@ -527,42 +727,60 @@ 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[:unapproved_candidate_count])
+                   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
         # contextual action, shown only when the analysis found nothing
         # usable and unapproved application-defined groups actually exist on
         # a configured user source. Deliberately not a configuration
-        # workflow -- it says what Karst found and offers to show it, and
-        # names nothing it has not been approved to run.
-        def candidate_review(count)
-          return "" unless count&.positive?
+        # workflow -- it names only the candidates which may be explicitly
+        # approved in this result, and never executes them merely by rendering.
+        def candidate_review(state, result)
+          candidates = state[:unapproved_candidates]
+          return "" if candidates.empty? || !state[:csrf_token]
+
+          fields = candidates.map { |candidate| candidate_checkbox(candidate) }.join
+          "<form class=\"candidate-review\" method=\"post\" action=\"/karst\">#{approval_alert(state)}" \
+            "<p>Karst found application-defined user groups in your app. " \
+            "Select only the populations Karst may try, then rerun this analysis:</p>#{fields}" \
+            "#{candidate_form_fields(state, result)}" \
+            "<button type=\"submit\">Approve selected and retry</button></form>"
+        end
+
+        def candidate_form_fields(state, result)
+          hidden("operation", "approve_populations") + hidden("csrf_token", state[:csrf_token]) +
+            hidden("path", result.path) + hidden("method", result.http_method)
+        end
+
+        def approval_alert(state)
+          error = state[:population_approval_error]
+          "<p class=\"hint\" role=\"alert\">#{escape(error)}</p>" if error
+        end
 
-          "<p class=\"candidate-review\">Karst found #{escape(count)} application-defined user " \
-            "#{count == 1 ? 'group' : 'groups'} that could be tried. " \
-            "<a href=\"/karst/populations\">Review candidate groups</a></p>"
+        def candidate_checkbox(candidate)
+          key = [candidate.principal_source, candidate.model_name, candidate.method_name].join("::")
+          "<label><input type=\"checkbox\" name=\"population[]\" value=\"#{escape(key)}\">" \
+            "#{escape(candidate.method_name)} <small>(#{escape(candidate.model_name)})</small></label>"
         end
 
         def usable_cards(outcomes, result, csrf_token)
           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
@@ -570,66 +788,63 @@ module Karst
         def usable_principal(outcome, result, csrf_token)
           writes = outcome.writes_observed ? " — ⚠ #{escape(outcome.write_count)} database writes observed" : ""
           action = test_as_form(outcome.principal, result.path, csrf_token)
-          evidence = resource_evidence(outcome, result)
           "<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)}#{evidence}</article>"
+            "#{escape(outcome.elapsed_ms)}ms</p>#{identity_note(outcome)}#{sampled_for(outcome)}</article>"
         end
 
-        # A compact, secondary line -- deliberately below the observed
-        # outcome and above any resource evidence, never a card of its own --
-        # so it augments a usable principal without competing with Test as,
-        # the observed outcome, or resource evidence for attention. Sampling
-        # evidence, not an authorization claim: see PrincipalSampler.
-        def sampled_for(outcome)
-          reasons = outcome.sampling_reasons
-          return "" if reasons.nil? || reasons.empty?
+        # 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\">Sampled for: #{escape(reasons.join(' · '))}</p>"
+          "<p class=\"meta\">⚠ #{escape(identity_summary(evidence))}</p>"
         end
 
-        def resource_evidence(outcome, result)
-          evidence = Access::ResourceEvidence.for_outcome(outcome: outcome, path: result.path,
-                                                          http_method: result.http_method)
-          return "" if evidence.limitation || evidence.relationships.empty?
-
-          "<div class=\"related-state\"><strong>Related state</strong>" \
-            "#{relationship_groups(evidence.relationships)}</div>"
-        rescue StandardError
-          ""
+        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 relationship_groups(relationships)
-          relationships.group_by { |item| [item.from_model, item.from_id] }.map do |key, items|
-            model, id = key
-            "<p><strong>#{escape(model)} ##{escape(id)}</strong></p><ul>#{relationship_rows(items)}</ul>"
-          end.join
+        def observed_label(evidence)
+          evidence.observed ? "#{evidence.observed.model_name} ##{evidence.observed.id}" : "no principal"
         end
 
-        def relationship_rows(relationships)
-          relationships.map do |item|
-            "<li>#{escape(item.column)} → #{escape(item.to_model)} ##{escape(item.to_id)}</li>"
-          end.join
+        # A compact, secondary line below the observed outcome, never a card
+        # of its own, so it augments a usable principal without competing with
+        # Test as or the observed outcome for attention. Sampling evidence,
+        # not an authorization claim: see PrincipalSampler.
+        def sampled_for(outcome)
+          reasons = outcome.sampling_reasons
+          return "" if reasons.nil? || reasons.empty?
+
+          "<p class=\"meta\">Sampled for: #{escape(reasons.join(' · '))}</p>"
         end
 
         # -- 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
@@ -658,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)