karst 0.2.0 → 0.4.0

data/lib/karst/access/sweep.rb

@@ -1,28 +1,37 @@
 # frozen_string_literal: true
 
-require "active_support/notifications"
-require "uri"
-require_relative "probe_application"
-require_relative "database_isolation"
+require_relative "errors"
+require_relative "local_path"
+require_relative "probe"
+require_relative "outcome_groups"
 require_relative "../identity"
 require_relative "../value"
 
 module Karst
   module Access
-    class Error < StandardError; end
-    class UnsafeTarget < Error; end
-    class UnsupportedMethod < Error; end
-    class Unavailable < Error; end
-
     # sampling_reasons is a frozen Array of short evidence strings (e.g.
     # "role=local_admin", "source=authors") explaining why PrincipalSampler
     # or PrincipalSelection deliberately included this principal, or an
     # empty Array when the principal came from plain first-N/fill sampling
     # or was supplied directly rather than through a sampler. This is
     # sampling evidence, not an authorization claim.
+    #
+    # `principal` is the *requested* identity -- what Karst was asked to
+    # execute as, nil for a deliberate anonymous probe -- and is intent, not
+    # evidence. What the application actually resolved lives in `identity`
+    # (a Karst::Identity::Evidence), and only its #confirmation says whether
+    # the two agree. Nothing may conclude "this request ran as User#123" from
+    # `principal` alone.
+    #
+    # controller/action are the controller class name and action the request
+    # actually dispatched to, observed from the probe request's own env, or
+    # nil when it never reached a controller.
+    #
+    # Every evidence field is Access::Probe's observation of the target
+    # request alone: write_count never includes identity setup/teardown.
     Outcome = Value.define(:principal, :status, :redirect, :exception_class,
                            :writes_observed, :write_count, :elapsed_ms, :database_rollback_attempted,
-                           :sampling_reasons, :body_marker_observed, :halted_callback)
+                           :sampling_reasons, :halted_callback, :identity, :controller, :action)
 
     # candidate_pool_size is nil unless the caller supplying `principals` (see
     # Access::PrincipalSampler::Result) knows it sampled from a bounded
@@ -31,14 +40,20 @@ module Karst
     # principal was considered.
     Result = Value.define(:path, :http_method, :outcomes, :elapsed_ms, :aborted_reason, :database_isolation,
                           :candidate_pool_size) do
+      # Semantic outcome groups (see Access::OutcomeGroups), largest first,
+      # as semantic key => member outcomes.
       def groups
-        outcomes.group_by { |item| [item.status, item.redirect, item.exception_class, item.halted_callback] }
+        OutcomeGroups.group(outcomes).to_h { |group| [group.key, group.outcomes] }
       end
     end
 
-    # Sequentially observes one concrete local GET using a fresh integration
-    # session and a rollback-only transaction for every bounded principal.
-    # rubocop:disable Metrics/ClassLength
+    # Runs one concrete local GET as each of a bounded set of principals, in
+    # order, and collects what happened to each. Every request is one
+    # Access::Probe call -- a fresh session and a rollback-only transaction per
+    # principal -- so a sweep's per-principal evidence is exactly what
+    # reproducing that request as that principal observes. Sweep itself owns
+    # only the population: bounding it, and attaching why each principal was
+    # sampled.
     class Sweep
       # sampling_reasons optionally maps a principal (by Ruby equality, so
       # the same Active Record identity even across separate instances) to
@@ -46,9 +61,8 @@ module Karst
       # Access::PrincipalSampler::Candidate/PrincipalSelection. A principal
       # with no entry simply gets an empty Array on its Outcome.
       # rubocop:disable Metrics/ParameterLists
-      # rubocop:disable Metrics/MethodLength
       def initialize(path:, principals:, http_method: "GET", limit: Karst.config.access_sweep_limit,
-                     application: nil, candidate_pool_size: nil, sampling_reasons: {}, body_includes: nil)
+                     application: nil, candidate_pool_size: nil, sampling_reasons: {})
         @path = normalize_path(path)
         @http_method = http_method.to_s.upcase
         raise UnsupportedMethod, "access sweeps support GET only" unless @http_method == "GET"
@@ -56,23 +70,20 @@ module Karst
 
         @principals = principals
         @limit = limit
-        @application = application || Rails.application
-        @probe_application = build_probe_application
+        @probe = Probe.new(application || Rails.application)
         @candidate_pool_size = candidate_pool_size
         @sampling_reasons = sampling_reasons
-        @body_includes = body_includes
       end
-      # rubocop:enable Metrics/MethodLength
       # rubocop:enable Metrics/ParameterLists
 
       def call
         raise Unavailable, "access sweeps are development-only" unless Rails.env.development?
         raise Unavailable, "Karst is disabled (config.enabled)" unless Karst.enabled?
 
-        require "action_dispatch/testing/integration" unless defined?(ActionDispatch::Integration::Session)
-
         started = monotonic
-        outcomes = bounded_principals.map { |principal| probe(principal) }
+        outcomes = bounded_principals.map do |principal|
+          outcome(principal, @probe.call(principal: principal, http_method: @http_method, target: @path))
+        end
         Result.new(path: @path, http_method: @http_method, outcomes: outcomes.freeze,
                    elapsed_ms: elapsed(started), aborted_reason: nil,
                    database_isolation: :same_connection_rollback_attempted,
@@ -82,14 +93,7 @@ module Karst
       private
 
       def normalize_path(value)
-        raw = value.to_s.split("?", 2).first
-        uri = URI.parse(raw)
-        local = uri.relative? && raw.start_with?("/") && !raw.start_with?("//")
-        raise UnsafeTarget, "target must be a local application path" unless local
-
-        raw
-      rescue URI::InvalidURIError
-        raise UnsafeTarget, "target must be a valid local application path"
+        LocalPath.path(value)
       end
 
       def valid_limit?(limit)
@@ -102,87 +106,14 @@ module Karst
         source.each.lazy.take(@limit).to_a
       end
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-      def probe(principal)
-        session = ActionDispatch::Integration::Session.new(@probe_application)
-        configure_host(session)
-        started = monotonic
-        status = redirect = exception_class = nil
-        body_marker_observed = nil
-        halted_callback = nil
-        writes = 0
-        callback = lambda do |_name, _start, _finish, _id, payload|
-          writes += 1 if DatabaseIsolation.mutation?(payload[:sql])
-        end
-        halt_observer = lambda do |_name, _start, _finish, _id, payload|
-          halted_callback = payload[:filter]
-        end
-
-        with_rollback do
-          ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
-            Karst::Identity.with(session, principal) do
-              ActiveSupport::Notifications.subscribed(halt_observer, "halted_callback.action_controller") do
-                session.get(@path)
-              end
-              rendered_exception = request_exception(session)
-              if rendered_exception
-                exception_class = rendered_exception.class.name
-              else
-                status = session.response.status
-                if @body_includes && session.response.respond_to?(:body)
-                  body_marker_observed = session.response.body.to_s.include?(@body_includes.to_s)
-                end
-                redirect = clean_redirect(session.response.location) if status >= 300 && status < 400
-              end
-            end
-          end
-        rescue StandardError => e
-          exception_class = e.class.name
-        end
-        Outcome.new(principal: Karst::Identity.describe(principal), status: status, redirect: redirect,
-                    exception_class: exception_class, writes_observed: writes.positive?, write_count: writes,
-                    elapsed_ms: elapsed(started), database_rollback_attempted: true,
+      def outcome(principal, observed)
+        writes = observed.write_count
+        Outcome.new(principal: observed.identity.requested, status: observed.status, redirect: observed.redirect,
+                    exception_class: observed.exception_class, writes_observed: writes.positive?,
+                    write_count: writes, elapsed_ms: observed.elapsed_ms, database_rollback_attempted: true,
                     sampling_reasons: (@sampling_reasons[principal] || []).freeze,
-                    body_marker_observed: body_marker_observed, halted_callback: halted_callback)
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-
-      def with_rollback
-        raise Unavailable, "Active Record rollback isolation is unavailable" unless defined?(ActiveRecord::Base)
-
-        ActiveRecord::Base.transaction(requires_new: true) do
-          yield
-          raise ActiveRecord::Rollback
-        end
-      end
-
-      def build_probe_application
-        ProbeApplication.for(@application)
-      rescue ProbeApplication::ConstructionError => e
-        raise Unavailable, e.message, cause: e
-      end
-
-      def configure_host(session)
-        return unless @probe_application.respond_to?(:host) && @probe_application.host
-
-        session.host!(@probe_application.host)
-      end
-
-      # Rails may either re-raise an application exception or render it through
-      # ShowExceptions, depending on host and Rails-version configuration. The
-      # latter records the original exception in the integration request env.
-      def request_exception(session)
-        return unless session.respond_to?(:request) && session.request
-
-        session.request.get_header("action_dispatch.exception")
-      end
-
-      def clean_redirect(location)
-        return nil if location.to_s.empty?
-
-        URI.parse(location).tap { |uri| uri.query = nil }.to_s
-      rescue URI::InvalidURIError
-        location.to_s.split("?", 2).first
+                    halted_callback: observed.halted_callback, identity: observed.identity,
+                    controller: observed.controller, action: observed.action)
       end
 
       def monotonic
@@ -193,6 +124,5 @@ module Karst
         ((monotonic - started) * 1000.0).round(1)
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/karst/cli/identity_serialization.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Karst
+  module CLI
+    # The one place a Karst::Identity::Evidence becomes the JSON/MCP-facing
+    # identity document, shared by Karst::CLI::Verification and
+    # Karst::CLI::Reproduction so the two schemas can never describe identity
+    # evidence differently -- a probe's `identity` document means the same
+    # thing regardless of which adapter produced it.
+    module IdentitySerialization
+      private
+
+      # The whole point of this schema. `requested` is intent, `observed` is
+      # what the application resolved while running the request, and
+      # `confirmation` is the only field that says whether a principal claim
+      # about this request is true. Anything other than
+      # "confirmed"/"confirmed_anonymous" means it is not.
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def identity_document(evidence)
+        return nil unless evidence
+
+        {
+          requested: evidence.requested && principal(evidence.requested),
+          observed: observed_principal(evidence.observed),
+          confirmation: evidence.confirmation.to_s,
+          observed_at: evidence.observed_at&.to_s,
+          observation_source: evidence.observation_source&.to_s,
+          observation_error: evidence.observation_error,
+          establishment: evidence.establishment&.to_s,
+          establishment_error: evidence.establishment_error,
+          cleanup_error: evidence.cleanup_error,
+          changed_during_request: evidence.changed_during_request
+        }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def observed_principal(value)
+        return nil unless value
+
+        { model: value.model_name.to_s, id: primitive_id(value.id) }
+      end
+
+      def principal(value)
+        # JSON is also the MCP contract. Framework-inferred login identifiers
+        # must never cross that machine-readable boundary. An application-
+        # authored principal_label remains explicit configuration and keeps
+        # its longstanding serialization behavior.
+        label = if Karst.config.principal_label
+                  value.display_label.to_s
+                else
+                  "#{value.model_name} ##{value.id}"
+                end
+        { model: value.model_name.to_s, id: primitive_id(value.id), label: label }
+      end
+
+      def primitive_id(value)
+        value.is_a?(Integer) ? value : value.to_s
+      end
+
+      # Says what the application actually did with identity, never what was
+      # asked of it.
+      def identity_line(evidence)
+        case evidence.confirmation
+        when :confirmed then "observed #{observed_label(evidence)} (identity confirmed)"
+        when :confirmed_anonymous then "observed no principal (anonymous confirmed)"
+        when :absent then "requested #{requested_label(evidence)}, observed no principal (NOT confirmed)"
+        when :mismatch then "requested #{requested_label(evidence)}, observed #{observed_label(evidence)} (MISMATCH)"
+        when :contaminated then "anonymous probe observed #{observed_label(evidence)} (CONTAMINATED)"
+        else "identity unobservable: #{evidence.observation_error}"
+        end
+      end
+
+      def observed_label(evidence)
+        evidence.observed ? "#{evidence.observed.model_name} ##{evidence.observed.id}" : "no principal"
+      end
+
+      def requested_label(evidence)
+        evidence.requested ? "#{evidence.requested.model_name} ##{evidence.requested.id}" : "anonymous"
+      end
+    end
+  end
+end

data/lib/karst/cli/outcome_summary.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module Karst
+  module CLI
+    # The bounded, human-readable outcome lines for one probe stage (the
+    # ordinary sample, one population retry), built from already-computed
+    # Access::OutcomeGroups groups.
+    #
+    # Counts, not conclusions: each line is one semantic outcome group and
+    # the number of users that observed it, largest first. The largest group
+    # is only ever marked by position -- Karst never calls it "dominant",
+    # "most", or "typical", so a close split (12 / 11 / 9) reads as exactly
+    # that. When one group is strictly larger than every other, its users are
+    # not listed (it is the outcome the rest differ from); every other group
+    # names up to MAX_EXAMPLES of its users, which are the ones worth
+    # inspecting. When the largest count is tied, no group is singled out and
+    # every group names examples.
+    #
+    # Output stays bounded however many users were tested: at most
+    # MAX_OUTCOMES group lines (verified-usable groups are always shown -- they
+    # are the answer to the question the sweep asks), one examples line per
+    # listed group, and one line summarizing whatever else was observed. The
+    # complete per-user evidence stays in `--json`.
+    class OutcomeSummary
+      MAX_OUTCOMES = 5
+      MAX_EXAMPLES = 3
+
+      def initialize(groups, indent: "  ")
+        @groups = groups
+        @indent = indent
+      end
+
+      def lines
+        return [] if @groups.empty?
+
+        width = shown.map { |group| group.count.to_s.size }.max
+        rows = shown.flat_map { |group| group_lines(group, width) }
+        rows << hidden_line if hidden.any?
+        rows
+      end
+
+      # One outcome group as a single line of observed facts, in Karst's own
+      # terms (see Web::Panel#outcome_title and CLI::Verification's
+      # response evidence) -- never "denied", "allowed", or any other
+      # authorization claim the application itself did not make.
+      def describe(group)
+        item = group.representative
+        parts = [response(item), (dispatch(item) if dispatch_varies?),
+                 (writes(item.write_count) if item.writes_observed), ("verified usable" if group.usable)]
+        parts.insert(1, "halted at #{item.halted_callback}") if item.halted_callback
+        parts.compact.join(" · ")
+      end
+
+      private
+
+      def group_lines(group, width)
+        line = ["#{@indent}#{group.count.to_s.rjust(width)}  #{describe(group)}"]
+        line << "#{@indent}#{' ' * width}    #{examples(group)}" if examples?(group)
+        line
+      end
+
+      def shown
+        @shown ||= @groups.each_with_index.select { |group, index| index < MAX_OUTCOMES || group.usable }
+                          .map(&:first)
+      end
+
+      def hidden
+        @hidden ||= @groups - shown
+      end
+
+      def hidden_line
+        users = hidden.sum(&:count)
+        "#{@indent}+#{hidden.size} more #{hidden.size == 1 ? 'outcome' : 'outcomes'} " \
+          "(#{users} #{users == 1 ? 'user' : 'users'}); --json lists every outcome"
+      end
+
+      def examples?(group)
+        return false if @groups.size == 1
+
+        !(unique_largest? && group.equal?(@groups.first))
+      end
+
+      def unique_largest?
+        @groups.size == 1 || @groups[0].count > @groups[1].count
+      end
+
+      def examples(group)
+        labels = group.outcomes.first(MAX_EXAMPLES).map { |item| label(item.principal) }
+        remaining = group.count - labels.size
+        labels << "+#{remaining} more" if remaining.positive?
+        labels.join(", ")
+      end
+
+      def label(principal)
+        principal ? principal.display_label.to_s : "anonymous request"
+      end
+
+      def response(item)
+        return "exception #{item.exception_class}" if item.exception_class
+        return "no response observed" unless item.status
+
+        status = status_title(item.status)
+        item.redirect ? "#{status} → #{item.redirect}" : status
+      end
+
+      def status_title(status)
+        phrase = Rack::Utils::HTTP_STATUS_CODES[status]
+        phrase ? "#{status} #{phrase}" : status.to_s
+      end
+
+      # Two groups must never read identically. Dispatch is part of the
+      # semantic key but normally uniform for one path, so it is printed only
+      # when groups in this stage actually disagree about it.
+      def dispatch_varies?
+        return @dispatch_varies if defined?(@dispatch_varies)
+
+        @dispatch_varies = @groups.map { |group| dispatch(group.representative) }.uniq.size > 1
+      end
+
+      def dispatch(item)
+        item.controller ? "#{item.controller}##{item.action}" : "no controller dispatched"
+      end
+
+      def writes(count)
+        "#{count} database #{count == 1 ? 'write' : 'writes'}"
+      end
+    end
+  end
+end

data/lib/karst/cli/principal_reference.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../identity"
+
+module Karst
+  module CLI
+    # Parses and resolves a human-supplied "--as MODEL:ID" reference (e.g.
+    # "User:72") into an existing principal, entirely through
+    # Karst::Identity.resolve -- the same configured-source-only lookup the
+    # browser's own Test As form already uses (see
+    # Karst::Web::BrowserIdentity#assume). There is no bypass here: a model
+    # name or id that Identity.resolve does not recognize resolves to
+    # nothing, exactly as it would for Test As, rather than falling back to
+    # Object#const_get/Model.find against an arbitrary class name.
+    module PrincipalReference
+      Reference = Struct.new(:model_name, :id)
+
+      # Format-only validation, with no dependency on a booted application or
+      # configured principal sources -- callers use this to reject a
+      # malformed --as value immediately, before Identity.resolve is even
+      # reachable.
+      def self.parse(value)
+        model_name, id = value.to_s.split(":", 2)
+        if model_name.to_s.empty? || id.to_s.empty?
+          raise ArgumentError, "--as must be MODEL:ID, e.g. \"User:72\" (got #{value.inspect})"
+        end
+
+        Reference.new(model_name, id)
+      end
+
+      # Resolves `value` to an existing principal, or raises ArgumentError --
+      # never nil, and never a fallback to sampling or to anonymous. A
+      # caller who explicitly asked to run as one principal gets that
+      # principal or a clear failure, not a silent substitute.
+      #
+      # `sources:`, when given, is the operation's already-resolved principal
+      # source Hash (see Karst::Identity::Snapshot).
+      def self.resolve(value, sources: nil)
+        reference = parse(value)
+        lookup = { model_name: reference.model_name, id: reference.id }
+        lookup[:sources] = sources if sources
+        principal = Identity.resolve(**lookup)
+        return principal if principal
+
+        raise ArgumentError,
+              "--as #{value} did not resolve: Karst found no #{reference.model_name} ##{reference.id} " \
+              "in its configured principal source(s)"
+      end
+    end
+  end
+end