karst 0.2.0 → 0.4.0

data/lib/karst/access/population_discovery.rb

@@ -14,6 +14,9 @@ module Karst
 
       Candidate = Value.define(:model_name, :method_name, :principal_source)
 
+      UNRESOLVED = Object.new.freeze
+      private_constant :UNRESOLVED
+
       ModelGroup = Value.define(:model_name, :candidate_names, :principal_source) do
         def candidates
           candidate_names.map do |method_name|
@@ -28,6 +31,20 @@ module Karst
         end
       end
 
+      # `principal_sources:`, when given, is either the caller's already-
+      # resolved effective principal source Hash (see
+      # Karst::Identity::Snapshot), or a zero-argument callable that resolves
+      # to one -- used, at most once, lazily, only if a check here actually
+      # needs it (#confirms? never does). The callable form lets a caller
+      # hand over a source of truth that is not resolved yet at construction
+      # time but will be by the time this discovery's #call actually runs
+      # (see Karst::Web::Middleware, which builds one discovery instance
+      # before resolving the operation's Identity::Snapshot and reuses it
+      # afterward). Omitted, configuration is resolved here instead.
+      def initialize(principal_sources: UNRESOLVED)
+        @principal_sources = principal_sources
+      end
+
       def call
         Result.new(model_groups: model_groups, load_warning: @load_warning)
       end
@@ -119,7 +136,7 @@ module Karst
       # and re-parse model source once per model group too.
       def principal_source_klasses
         @principal_source_klasses ||= begin
-          sources = Karst.config.principal_sources || {}
+          sources = resolved_principal_sources || {}
           sources.each_with_object({}) do |(name, source), memo|
             klass = source.record_klass
             memo[name] = klass if klass
@@ -127,6 +144,13 @@ module Karst
         end
       end
 
+      def resolved_principal_sources
+        return @principal_sources.call if @principal_sources.respond_to?(:call)
+        return Karst.config.principal_sources if @principal_sources.equal?(UNRESOLVED)
+
+        @principal_sources
+      end
+
       # A deliberately small Ripper AST reader. It recognizes only literal
       # names and the two callable forms accepted here: -> {} and lambda {}.
       # rubocop:disable Metrics/ClassLength

data/lib/karst/access/principal_source.rb

@@ -19,12 +19,15 @@ module Karst
     class PrincipalSource
       attr_reader :name, :records, :populations
 
-      def initialize(name:, records:, populations: {})
+      # `evaluation` is internal: the shared memo cell #evaluated_once copies
+      # carry. nil (the default) evaluates `records` on every call.
+      def initialize(name:, records:, populations: {}, evaluation: nil)
         raise ArgumentError, "principal source #{name.inspect} must be callable" unless records.respond_to?(:call)
 
         @name = name.to_sym
         @records = records
         @populations = self.class.normalize_populations(@name, populations)
+        @evaluation = evaluation
       end
 
       # Evaluates the configured records callable. Never enumerates or
@@ -32,7 +35,10 @@ module Karst
       # Relation, exactly like Karst::Identity.principals already did for
       # the single-source case.
       def evaluate
-        records.call
+        return records.call unless @evaluation
+        return @evaluation[:records] if @evaluation.key?(:records)
+
+        @evaluation[:records] = records.call
       end
 
       # The Active Record class this source's records ultimately belong to,
@@ -53,6 +59,20 @@ module Karst
         nil
       end
 
+      # A copy of this source whose records callable runs at most once, for
+      # as long as the copy (and any #with_populations copy of it) lives: the
+      # first #evaluate result is reused by every later #evaluate and
+      # #record_klass. Configuration#principal_sources hands out these
+      # copies, one set per resolution, so a single operation holding one
+      # resolution (see Karst::Identity::Snapshot) never re-runs an
+      # application callable to sample, match approvals, and check Devise
+      # scopes, while the next resolution still evaluates afresh. `records`
+      # itself is unchanged, and a callable that raises is not memoized: each
+      # caller sees the failure, as before.
+      def evaluated_once
+        self.class.new(name: @name, records: @records, populations: @populations, evaluation: {})
+      end
+
       # A copy of this source with `extra` populations appended after its own
       # configured ones. Used by Karst::Access::ApprovedPopulations to fold
       # locally approved discovered scopes into the effective configuration,
@@ -66,7 +86,8 @@ module Karst
         merged = self.class.normalize_populations(@name, extra).reject { |name, _| @populations.key?(name) }
         return self if merged.empty?
 
-        self.class.new(name: @name, records: @records, populations: @populations.merge(merged))
+        self.class.new(name: @name, records: @records, populations: @populations.merge(merged),
+                       evaluation: @evaluation)
       end
 
       # Accepts a raw Hash of name => (callable, or {records:,

data/lib/karst/access/probe.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require "uri"
+require_relative "errors"
+require_relative "probe_application"
+require_relative "database_isolation"
+require_relative "identity_probe"
+require_relative "../identity"
+require_relative "../value"
+
+module Karst
+  module Access
+    # The one place Karst executes a request against the application and
+    # observes what it did.
+    #
+    # Access::Sweep ("which identities get through this route?") and
+    # Reproduction::Exercise ("what does this exact request do?") issue every
+    # request through #call and differ only in what they ask and how they
+    # present the answer. So one request, as one identity, against one target
+    # produces one observation, whichever feature -- and whichever CLI
+    # command, MCP tool, or panel operation above it -- asked.
+    #
+    # Every probe runs in three phases, and only the middle one is the request
+    # under test:
+    #
+    #   setup     Access::IdentityProbe#establish (sign-in requests and hooks),
+    #             plus Karst's own Warden sign-in when it can only be applied
+    #             inside the target request itself (see Identity.establishing)
+    #   target    exactly one request, observed
+    #   teardown  Access::IdentityProbe#release (sign-out requests and hooks)
+    #
+    # Target evidence -- mutating SQL, the halted callback, the controller
+    # lifecycle, renders -- is recorded only by subscriptions that exist for
+    # the target request's own duration, only on this thread, and never while
+    # Karst is doing its own identity work inside that request. A sign-in
+    # that inserts a session row, a sign-out that deletes it, or a Devise
+    # :trackable UPDATE is setup/teardown, never the route's behavior; a write
+    # the route itself makes always is. Writes are counted when attempted, so
+    # the rollback below never erases them from the evidence.
+    #
+    # All three phases run inside one rollback-only transaction on the same
+    # connection -- containment for database writes on that connection and
+    # nothing else (jobs, mail, outbound HTTP, files, and other connections are
+    # not contained).
+    #
+    # Three kinds of failure are kept apart rather than folded together:
+    #
+    #   - The target raising (or rendering a captured exception) is observed
+    #     application behavior: exception_class/exception_phase.
+    #   - Identity setup failing is identity evidence (identity.establishment
+    #     :failed and its error). The target still runs and is still
+    #     observed -- except when Karst's own in-request sign-in raised, in
+    #     which case the route never ran and nothing is reported for it.
+    #   - Karst failing to observe (one of its own subscribers raising, a
+    #     misconfigured observe_identity, a request that never reached the
+    #     application) fails the call with ObservationError or the
+    #     configuration error itself. Evidence Karst could not gather is never
+    #     reported as the application having done nothing.
+    class Probe
+      # The authoritative observation of one target request.
+      #
+      # controller/action are the controller the target request dispatched to,
+      # read from its own Rack env (nil when it reached none).
+      # controller_completed is whether process_action finished without an
+      # exception (nil when process_action never ran). status, redirect
+      # (query-stripped), response_content_type, and route_params (the
+      # router's own path_parameters, minus controller/action) are read only
+      # when the target completed, so a raising target never inherits an
+      # earlier request's response. halted_callback is the filter exactly as
+      # Rails reported it. write_count counts mutating SQL statements the
+      # target attempted. elapsed_ms covers the whole probe, setup and
+      # teardown included.
+      Observation = Value.define(
+        :identity, :controller, :action, :controller_completed, :status, :redirect, :response_content_type,
+        :halted_callback, :exception_class, :exception_phase, :rendered, :write_count, :route_params, :elapsed_ms
+      )
+
+      def initialize(application)
+        @endpoint = ProbeApplication.for(application)
+      rescue ProbeApplication::ConstructionError => e
+        raise Unavailable, e.message, cause: e
+      end
+
+      # `target` is a local path, including any query string, exactly as it
+      # is sent. `body` travels as the request body, never as query
+      # parameters.
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def call(principal:, target:, http_method: "GET", body: nil, headers: {})
+        identity = IdentityProbe.new(principal)
+        session = open_session(identity)
+        method = http_method.to_s.downcase.to_sym
+        window = TargetWindow.new(identity)
+        started = monotonic
+        with_rollback do
+          # Never raises: a probe whose identity could not be established
+          # still runs, and reports what the application actually saw.
+          identity.establish(session)
+          begin
+            window.run { session.process(method, target, params: body, headers: headers) }
+            # Strictly before release: clearing the identity is exactly what
+            # would make a completed request look anonymous, and a sign-out
+            # request would replace the target's env and response.
+            identity.observe(:request_completion)
+            window.capture(session)
+          ensure
+            identity.release(session)
+          end
+        end
+        window.verify!
+        window.observation(elapsed(started))
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+      private
+
+      # One fresh integration session per probe, reused for setup, target,
+      # and teardown so cookies behave like one real client.
+      def open_session(identity)
+        require "action_dispatch/testing/integration" unless defined?(ActionDispatch::Integration::Session)
+
+        session = ActionDispatch::Integration::Session.new(identity.endpoint(@endpoint))
+        session.host!(@endpoint.host) if @endpoint.respond_to?(:host) && @endpoint.host
+        session
+      end
+
+      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 monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def elapsed(started)
+        ((monotonic - started) * 1000.0).round(1)
+      end
+
+      # Everything observed about one target request: open only while that
+      # request runs, on the thread that runs it.
+      # rubocop:disable Metrics/ClassLength
+      class TargetWindow
+        def initialize(identity)
+          @identity = identity
+          @thread = Thread.current
+          @writes = 0
+          @render_events = []
+          @paused = false
+        end
+
+        # rubocop:disable Naming/BlockForwarding -- anonymous block forwarding
+        # needs Ruby 3.1; this file runs on Ruby 2.7.
+        def run(&request)
+          @identity.begin_target
+          subscribed(&request)
+          @completed = true
+        rescue Identity::EstablishmentError => e
+          # Karst's own sign-in raised inside the request, before the
+          # application dispatched it: identity setup failed, and the route
+          # never ran.
+          @identity.establishment_failed(e.message)
+        rescue StandardError => e
+          target_raised(e)
+        end
+        # rubocop:enable Naming/BlockForwarding
+
+        def capture(session)
+          env = @identity.request_env
+          @controller, @action = dispatched(env)
+          @controller_completed = !@dispatch.key?(:exception) if @dispatch
+          return unless @completed && env
+
+          # Rails may render an application exception through ShowExceptions
+          # rather than re-raise it, depending on host and Rails-version
+          # configuration; the original is then recorded on the env.
+          @exception = env["action_dispatch.exception"]
+          return if @exception
+
+          # Only now is session.request/session.response provably the target's:
+          # ActionDispatch::Integration::Session reassigns them only after the
+          # request returns without raising.
+          @status = session.response.status
+          @redirect = clean_redirect(session.response.location) if @status >= 300 && @status < 400
+          @response_content_type = response_content_type(session)
+          @route_params = route_params(session)
+        end
+
+        # A misconfigured observation seam is a configuration error and says
+        # so; any other failure of Karst's own observation means the evidence
+        # is incomplete, and none of it is reported.
+        def verify!
+          return unless @failure
+          raise @failure if @failure.is_a?(Identity::ConfigurationError)
+
+          raise ObservationError,
+                "Karst could not observe this request (#{@failure.class}: #{@failure.message}); " \
+                "no evidence was reported for it",
+                cause: @failure
+        end
+
+        def observation(elapsed_ms)
+          Observation.new(
+            identity: @identity.evidence, controller: @controller, action: @action,
+            controller_completed: @controller_completed, status: @status, redirect: @redirect,
+            response_content_type: @response_content_type, halted_callback: @halted_callback,
+            exception_class: @exception&.class&.name, exception_phase: (exception_phase if @exception),
+            rendered: rendered, write_count: @writes, route_params: @route_params, elapsed_ms: elapsed_ms
+          )
+        end
+
+        private
+
+        # Only an exception from a request that actually reached the
+        # application is the application's own; anything earlier is Karst
+        # failing to issue the request at all.
+        def target_raised(error)
+          if @identity.request_env
+            @exception = error
+          else
+            @failure ||= error # rubocop:disable Naming/MemoizedInstanceVariableName
+          end
+        end
+
+        # Notification subscriptions are process-wide; #recording? keeps a
+        # concurrent request on another thread of a real development server
+        # from ever being counted as this target's evidence.
+        def subscribed(&block)
+          notifications = ActiveSupport::Notifications
+          notifications.subscribed(guarded(:record_write), "sql.active_record") do
+            notifications.subscribed(guarded(:record_halt), "halted_callback.action_controller") do
+              notifications.subscribed(guarded(:record_render), "!render_template.action_view") do
+                notifications.subscribed(guarded(:record_dispatch), "process_action.action_controller", &block)
+              end
+            end
+          end
+        end
+
+        # A subscriber that raises would raise into the application's own
+        # instrumented code -- a SQL statement, a callback chain, a
+        # transaction -- and surface as the target's exception. Karst's
+        # failure is kept as Karst's instead (see #verify!).
+        def guarded(handler)
+          lambda do |_name, _start, _finish, _id, payload|
+            send(handler, payload) if recording?
+          rescue StandardError => e
+            @failure ||= e
+          end
+        end
+
+        def recording?
+          Thread.current.equal?(@thread) && !@paused && !Identity.establishing?
+        end
+
+        def record_write(payload)
+          @writes += 1 if DatabaseIsolation.mutation?(payload[:sql])
+        end
+
+        def record_halt(payload)
+          @halted_callback ||= payload[:filter]
+          # The identity the application had established when this access
+          # decision was made -- not after the request unwound. Karst's own
+          # observation, so nothing it causes is the target's evidence.
+          pause { @identity.observe(:halted_callback) }
+        end
+
+        # "!render_template.action_view" -- not the higher-level, no-bang
+        # "render_template.action_view" -- because it is the one event
+        # ActionView::Template itself fires for every template, partial, and
+        # layout it renders, and the only one carrying that template's own
+        # relative virtual_path rather than an absolute source file. It fires
+        # once per Template#render call, whether that call completed or raised
+        # (payload[:exception]/[:exception_object] are set first when it
+        # raised), so it is a faithful, ordered record of what the target
+        # request rendered.
+        def record_render(payload)
+          return unless payload[:virtual_path]
+
+          @render_events << { virtual_path: payload[:virtual_path].to_s, completed: !payload.key?(:exception),
+                              exception_object: payload[:exception_object] }
+        end
+
+        # The last process_action to finish is the outermost one.
+        def record_dispatch(payload)
+          @dispatch = payload
+        end
+
+        def pause
+          @paused = true
+          yield
+        ensure
+          @paused = false
+        end
+
+        # Rails puts the dispatching controller on the request env before any
+        # callback runs, so this is present even for a halted request.
+        def dispatched(env)
+          instance = env && env["action_controller.instance"]
+          return [nil, nil] unless instance
+
+          [presence(instance.class.name), presence(instance.respond_to?(:action_name) ? instance.action_name : nil)]
+        rescue StandardError
+          [nil, nil]
+        end
+
+        def presence(value)
+          value.to_s.empty? ? nil : value.to_s
+        end
+
+        def rendered
+          @render_events.map { |event| { virtual_path: event[:virtual_path], completed: event[:completed] }.freeze }
+                        .freeze
+        end
+
+        # The most specific phase Karst can prove an observed exception
+        # occurred in, never guessed from its class or message.
+        #
+        # A render-level exception reaches the controller wrapped in a new
+        # ActionView::Template::Error (see ActionView::Template#handle_render_
+        # error), so the object the request ultimately raised is not the one
+        # "!render_template.action_view" recorded -- it is that object's
+        # #cause, or its #cause's #cause for a partial nested inside a
+        # template inside a layout. Walking #cause is therefore required to
+        # recognize a render exception at all once it has unwound past the
+        # template that raised it.
+        def exception_phase
+          return "render" if @render_events.any? { |event| same_exception?(@exception, event[:exception_object]) }
+          return "controller" if @dispatch&.key?(:exception)
+
+          "unknown"
+        end
+
+        def same_exception?(exception, candidate)
+          return false unless candidate
+
+          chain = exception
+          depth = 0
+          while chain && depth < 20
+            return true if chain.equal?(candidate)
+
+            chain = chain.respond_to?(:cause) ? chain.cause : nil
+            depth += 1
+          end
+          false
+        end
+
+        # The router's own path_parameters -- observed routing, not a second
+        # recognize_path guess that could disagree with what dispatched.
+        # nil when Karst observed no route.
+        def route_params(session)
+          raw = session.request.path_parameters
+          return nil unless raw.is_a?(Hash) && !raw.empty?
+
+          raw.each_with_object({}) do |(key, value), result|
+            result[key.to_s] = value unless %w[controller action].include?(key.to_s)
+          end
+        rescue StandardError
+          nil
+        end
+
+        def response_content_type(session)
+          value = session.response.content_type if session.response.respond_to?(:content_type)
+          value.to_s.empty? ? nil : value.to_s
+        rescue StandardError
+          nil
+        end
+
+        # Query-and-fragment-stripped, never just query-stripped: a redirect
+        # target is exactly as capable of carrying a credential in its
+        # fragment (an OAuth-style "/callback#access_token=...") as in its
+        # query string, and a fragment is never sent back to the server on
+        # the follow-up request, so there is no reason reproduction needs it
+        # either. The regex fallback below mirrors that -- it drops
+        # everything from the first "?" *or* "#", whichever comes first --
+        # so a Location Karst cannot even parse as a URI still cannot leak
+        # through the one delimiter the query-only split used to miss.
+        def clean_redirect(location)
+          text = location.to_s
+          return nil if text.empty?
+
+          uri = URI.parse(text)
+          uri.query = nil
+          uri.fragment = nil
+          uri.to_s
+        rescue StandardError
+          text.split(/[?#]/, 2).first
+        end
+      end
+      private_constant :TargetWindow
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end

data/lib/karst/access/search.rb

@@ -14,11 +14,11 @@ module Karst
     #
     # This is deliberately an orchestrator built on top of the existing
     # primitives rather than new behavior inside them. Access::Sweep still
-    # owns every actual request (and therefore every rollback, write
-    # observation, exception, and halted-callback observation), and
-    # CandidatePopulation still owns resolving one configured callable into
-    # bounded records. Search only decides what to run next and records what
-    # it chose not to run.
+    # issues every request (each one an Access::Probe, which owns every
+    # rollback, write observation, exception, and halted-callback
+    # observation), and CandidatePopulation still owns resolving one
+    # configured callable into bounded records. Search only decides what to
+    # run next and records what it chose not to run.
     #
     # Approval boundary: the populations considered here are exactly the
     # ones on the Karst::Access::PrincipalSource objects handed to this
@@ -164,10 +164,18 @@ module Karst
       def attempt_population(source_name, name, callable, source)
         return skip(source_name, name, :budget_exhausted) unless budget_remaining.positive?
 
-        resolved = candidate_records(source_name, name, callable, source)
+        resolved = resolve_population(source_name, name, callable, source)
         return resolved if resolved.is_a?(PopulationAttempt)
 
         sweep_population(source_name, name, resolved[:records], resolved[:population])
+      end
+
+      # A population that fails to *resolve* is reported as :unresolved. A
+      # failure while *probing* its records is not a fact about the
+      # population, so it is never folded into that state: it propagates
+      # exactly as it would from the ordinary sample.
+      def resolve_population(source_name, name, callable, source)
+        candidate_records(source_name, name, callable, source)
       rescue StandardError => e
         skip(source_name, name, :unresolved, error: "#{e.class}: #{e.message}")
       end