karst 0.2.0 → 0.4.0

data/lib/karst/configuration.rb

@@ -23,17 +23,45 @@ module Karst
   # Karst), already true by default wherever it should be. What remains
   # below is for exceptional applications: custom (non-Devise)
   # authentication, identity spread across several models, and a handful of
-  # deliberately unprominent bounds. See docs/advanced-configuration.md.
+  # deliberately unprominent bounds. Mutating MCP reproduction is a separate,
+  # default-off capability because same-connection rollback cannot contain
+  # arbitrary application side effects. See docs/advanced-configuration.md.
   class Configuration
     # None of these are normal configuration. `enabled` is an off switch for
     # the exceptional case where Karst's default (on in development/test) is
     # wrong for this environment. The rest are escape hatches for custom
     # (non-Devise) authentication -- principals, assume_identity,
     # clear_identity, principal_label, and the browser Test-as pair -- and
-    # are documented as such.
-    attr_accessor :enabled, :principals, :assume_identity, :clear_identity, :principal_label,
+    # are documented as such. `mcp_mutating_requests` is the narrowly scoped
+    # opt-in that lets an MCP client issue POST/PUT/PATCH/DELETE reproduction;
+    # it is false by default and does not affect human reproduction.
+    attr_accessor :enabled, :mcp_mutating_requests, :principals, :assume_identity, :clear_identity, :principal_label,
                   :assume_browser_identity, :clear_browser_identity
 
+    # How Karst observes which principal the *application itself* resolved
+    # while running a probe request -- the only thing that can turn "Karst
+    # was asked to run as User#123" into evidence that the request actually
+    # did. A callable taking one Karst::Identity::ObservationContext
+    # (#controller, #request, #env) and returning the application's runtime
+    # principal, or nil when the application resolved none:
+    #
+    #   config.observe_identity = ->(context) { context.controller&.current_user }
+    #
+    # `controller` is the exact ActionController instance that processed the
+    # request, present even when a before_action halted it, so an identity
+    # the application keeps in an instance variable, a Current attribute, or
+    # anything else Karst cannot know about is still observable. Returning
+    # nil/false means "the application ran this request anonymously"; raising
+    # (or returning something with no id) makes the observation unobservable,
+    # never confirmed.
+    #
+    # A Devise/Warden application needs none of this: Karst reads the
+    # application's own Warden proxy from the probe request instead (see
+    # Karst::Identity::Observer). With neither seam available, Karst reports
+    # identity as unobservable rather than assuming the requested principal
+    # is the one that ran.
+    attr_accessor :observe_identity
+
     # principal_populations is an escape hatch (committed, reviewable
     # populations for CI); the four bounds after it are advanced tuning an
     # ordinary developer should never need to see.
@@ -88,8 +116,10 @@ module Karst
       access_scenario: "artifact scenarios were removed; Karst analyzes routes, not record sweeps"
     }.freeze
 
+    # rubocop:disable Metrics/MethodLength
     def initialize
       @enabled = defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.development? || Rails.env.test? : false
+      @mcp_mutating_requests = false
       @access_sweep_limit = 25
       @principal_candidate_pool_size = 1_000
       @population_retry_limit = 3
@@ -97,8 +127,10 @@ module Karst
       @principal_populations = {}
       @configured_principal_sources = nil
       %i[@principals @assume_identity @clear_identity @principal_label
-         @assume_browser_identity @clear_browser_identity].each { |hook| instance_variable_set(hook, nil) }
+         @assume_browser_identity @clear_browser_identity
+         @observe_identity].each { |hook| instance_variable_set(hook, nil) }
     end
+    # rubocop:enable Metrics/MethodLength
 
     # An application-authored hint about meaningful candidate populations for
     # whatever config.principals returns -- a Hash of name => zero-argument
@@ -149,8 +181,22 @@ module Karst
     # what a "approved population" is. Resolved on every call rather than
     # memoized: an approval revoked, or a scope deleted, must stop being
     # executed on the next analysis without a server restart.
-    def principal_sources
-      Access::ApprovedPopulations.merge(configured_or_inferred_sources)
+    #
+    # That resolution is real work -- reading the approval (and selection)
+    # file, parsing model source, evaluating principal source callables -- so
+    # one high-level operation resolves it once and reuses the result (see
+    # Karst::Identity::Snapshot) rather than calling this repeatedly. Within
+    # one result, each source's records callable is evaluated at most once
+    # (see Access::PrincipalSource#evaluated_once).
+    #
+    # `record:`/`discovery:`, when given, are threaded straight to
+    # Access::ApprovedPopulations.merge -- a caller's already-loaded
+    # approval record and population discovery instance, reused instead of
+    # loaded and parsed again (see Karst::Identity::Snapshot).
+    def principal_sources(record: nil, discovery: nil)
+      sources = configured_or_inferred_sources
+      Access::ApprovedPopulations.merge(sources&.transform_values(&:evaluated_once), record: record,
+                                                                                     discovery: discovery)
     end
 
     def access_sweep_limit=(value)

data/lib/karst/identity/evidence.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "observation"
+
+module Karst
+  module Identity
+    # The three identities of one probe request, kept deliberately apart:
+    #
+    #   requested -- what the caller asked Karst to execute as (intent).
+    #                nil means an anonymous probe was requested.
+    #   establishment -- what Karst's own identity seam managed to set up
+    #                (setup), never evidence on its own.
+    #   observed  -- what the Rails application itself resolved as its
+    #                authenticated principal while running the request
+    #                (evidence).
+    #
+    # `confirmation` is the only field a machine consumer should read to
+    # decide whether a principal claim is true, and it fails closed:
+    #
+    #   :confirmed           requested a principal, observed that same one
+    #   :confirmed_anonymous requested anonymous, observed no principal
+    #   :mismatch            requested a principal, observed a different one
+    #   :absent              requested a principal, observed none
+    #   :contaminated        requested anonymous, observed a principal
+    #   :unobservable        Karst could not determine what identity the
+    #                        application used
+    #
+    # Only :confirmed and :confirmed_anonymous are evidence about identity.
+    Evidence = Value.define(:requested, :observed, :confirmation, :observed_at, :observation_source,
+                            :observation_error, :establishment, :establishment_error, :cleanup_error,
+                            :changed_during_request) do
+      def confirmed?
+        %i[confirmed confirmed_anonymous].include?(confirmation)
+      end
+
+      def anonymous_probe?
+        requested.nil?
+      end
+    end
+
+    # Derives one Evidence from the observations a probe actually collected.
+    module EvidenceBuilder
+      class << self
+        # `halt` is the observation taken at the moment an access callback
+        # halted the request -- the state the application had established
+        # when that access decision was made -- and `completion` the one
+        # taken after the request returned. Both may be nil (never attempted).
+        # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+        def build(requested:, halt: nil, completion: nil, establishment: nil,
+                  establishment_error: nil, cleanup_error: nil)
+          decisive = decisive_observation(halt, completion)
+          Evidence.new(
+            requested: requested,
+            observed: decisive&.observable? ? decisive.principal : nil,
+            confirmation: confirmation(requested, decisive),
+            observed_at: decisive&.observable? ? phase_of(decisive, halt) : nil,
+            observation_source: decisive&.source,
+            observation_error: decisive&.error,
+            establishment: establishment,
+            establishment_error: establishment_error,
+            cleanup_error: cleanup_error,
+            changed_during_request: changed?(halt, completion)
+          )
+        end
+        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+
+        private
+
+        # The halt moment is the one that explains an access decision, so it
+        # wins whenever it produced a real observation; a failed observation
+        # there still falls back to the completed request rather than
+        # discarding evidence Karst does hold.
+        def decisive_observation(halt, completion)
+          return halt if halt&.observable?
+          return completion if completion&.observable?
+
+          halt || completion
+        end
+
+        def phase_of(decisive, halt)
+          decisive.equal?(halt) ? :halted_callback : :request_completion
+        end
+
+        def confirmation(requested, decisive)
+          return :unobservable if decisive.nil? || !decisive.observable?
+          return anonymous_confirmation(decisive.principal) if requested.nil?
+          return :absent if decisive.principal.nil?
+
+          same?(requested, decisive.principal) ? :confirmed : :mismatch
+        end
+
+        def anonymous_confirmation(observed)
+          observed.nil? ? :confirmed_anonymous : :contaminated
+        end
+
+        def same?(requested, observed)
+          requested.model_name.to_s == observed.model_name.to_s &&
+            requested.id.to_s == observed.id.to_s
+        end
+
+        def changed?(halt, completion)
+          return false unless halt&.observable? && completion&.observable?
+
+          halt.principal != completion.principal
+        end
+      end
+    end
+  end
+end

data/lib/karst/identity/observation.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "devise_support"
+
+module Karst
+  module Identity
+    # The one place a principal object's stable model name is derived, shared
+    # by requested-identity description (Identity.describe) and runtime
+    # observation below, so the two can never disagree about what "User"
+    # means for the same object.
+    module Naming
+      module_function
+
+      def model_name_for(klass)
+        klass.respond_to?(:model_name) ? klass.model_name.name.to_s : klass.name.to_s
+      end
+    end
+
+    # What the *application* resolved as its own authenticated principal
+    # during a probe request -- never what Karst asked for. Deliberately
+    # narrower than PrincipalDescriptor: an observation carries no display
+    # label or authentication identifier, because it is evidence about a
+    # request rather than a record Karst selected and can describe.
+    ObservedPrincipal = Value.define(:model_name, :id)
+
+    # Handed to config.observe_identity. `controller` is the exact
+    # ActionController instance that processed the probe request (Rails sets
+    # env["action_controller.instance"] in ActionController::Metal#set_request!
+    # before any callback runs, so it is present even for a request halted in
+    # a before_action); `request` is an ActionDispatch::Request over the same
+    # env, and `env` the raw Rack env.
+    ObservationContext = Value.define(:controller, :request, :env)
+
+    # One attempt to observe the application's runtime principal.
+    # `principal` is an ObservedPrincipal, or nil for "the application
+    # resolved no principal" -- which is only meaningful when `error` is nil.
+    # `source` names which seam produced it (:configured, :warden), so a
+    # consumer can tell an application-authored observation from an inferred
+    # one. A non-nil `error` means Karst could not determine what identity the
+    # application used at all, and nothing may be concluded from `principal`.
+    Observation = Value.define(:principal, :source, :error) do
+      def observable?
+        error.nil?
+      end
+    end
+
+    # Observes the principal the Rails application actually used, from the
+    # runtime state of the probe request itself.
+    #
+    # Two seams, in order of authority:
+    #
+    #   1. config.observe_identity -- an application-authored callable given
+    #      the controller instance that processed the request. This is the
+    #      only seam that can observe an identity the application keeps
+    #      somewhere Karst cannot know about (a @current_user set by a
+    #      before_action, a Current attribute, a custom session lookup).
+    #
+    #   2. The Warden proxy on the probe request's own env, read through
+    #      Warden's public Proxy#user. For a Devise application this is the
+    #      same object Devise's own current_<scope> helper returns, and
+    #      reading it neither runs authentication strategies nor mutates the
+    #      request (Proxy#user only deserializes an existing session, unlike
+    #      Proxy#authenticate).
+    #
+    # With neither available, Karst reports the observation as unobservable
+    # rather than assuming the requested identity was the one that ran.
+    module Observer
+      UNCONFIGURED = "no runtime identity observation seam is available; " \
+                     "configure config.observe_identity (or use Karst's Devise/Warden integration)"
+
+      class << self
+        def observe(env, requested: nil)
+          return unobservable("the probe request environment was not captured") unless env.is_a?(Hash)
+
+          hook = Karst.config.observe_identity
+          return observe_with_hook(hook, env) if hook
+          return observe_with_warden(env, requested) if warden_proxy(env)
+
+          unobservable(UNCONFIGURED)
+        end
+
+        # Public so Identity.describe and observation agree on model naming.
+        def model_name_for(klass)
+          Naming.model_name_for(klass)
+        end
+
+        private
+
+        def observe_with_hook(hook, env)
+          raise ConfigurationError, "config.observe_identity must be callable" unless hook.respond_to?(:call)
+
+          observed(hook.call(context_for(env)), :configured)
+        rescue ConfigurationError
+          raise
+        rescue StandardError => e
+          unobservable("config.observe_identity raised #{e.class}: #{e.message}")
+        end
+
+        def context_for(env)
+          ObservationContext.new(controller: env["action_controller.instance"],
+                                 request: action_dispatch_request(env), env: env)
+        end
+
+        def action_dispatch_request(env)
+          return nil unless defined?(ActionDispatch::Request)
+
+          ActionDispatch::Request.new(env)
+        rescue StandardError
+          nil
+        end
+
+        # Every scope the application might have authenticated under, most
+        # likely first: the requested principal's own Devise scope, then every
+        # other registered one (so an anonymous probe contaminated under some
+        # *other* scope is still seen), then Warden's own default scope for a
+        # plain non-Devise Warden setup.
+        def observe_with_warden(env, requested)
+          proxy = warden_proxy(env)
+          scopes(requested).each do |scope|
+            user = scope ? proxy.user(scope: scope) : proxy.user
+            return observed(user, :warden) if user
+          end
+          Observation.new(principal: nil, source: :warden, error: nil)
+        rescue StandardError => e
+          unobservable("reading the Warden proxy raised #{e.class}: #{e.message}")
+        end
+
+        def scopes(requested)
+          registered = DeviseSupport.mappings.map(&:scope)
+          return [nil] if registered.empty?
+
+          preferred = requested && DeviseSupport.mapping_for(requested.class)&.scope
+          ([preferred] + registered).compact.uniq
+        end
+
+        # false and nil both mean "the application resolved no principal";
+        # anything that cannot state a stable identity is unobservable rather
+        # than silently reported as some principal.
+        def observed(value, source)
+          return Observation.new(principal: nil, source: source, error: nil) if value.nil? || value == false
+
+          id = identifier_of(value)
+          return unobservable("the observed principal (#{value.class}) has no usable id", source: source) if id.nil?
+
+          Observation.new(principal: ObservedPrincipal.new(model_name: model_name_for(value.class), id: id),
+                          source: source, error: nil)
+        rescue StandardError => e
+          unobservable("describing the observed principal raised #{e.class}: #{e.message}", source: source)
+        end
+
+        def identifier_of(value)
+          value.respond_to?(:id) ? value.id : nil
+        end
+
+        def warden_proxy(env)
+          proxy = env["warden"]
+          proxy if proxy.respond_to?(:user)
+        end
+
+        def unobservable(message, source: nil)
+          Observation.new(principal: nil, source: source, error: message)
+        end
+      end
+    end
+  end
+end

data/lib/karst/identity/warden_adapter.rb

@@ -49,6 +49,22 @@ module Karst
           defined?(Warden::Manager) && Warden::Manager.respond_to?(:on_request)
         end
 
+        # Drops any principal this thread queued but never consumed -- the
+        # exact state an anonymous probe must not inherit (see
+        # Access::IdentityProbe). A queued principal survives only until the
+        # next Warden request on this thread, so a probe whose request never
+        # reached Warden (construction failure, an exception before dispatch)
+        # would otherwise leave one behind for whichever probe ran next.
+        def discard_pending!
+          Karst::ExecutionContext.delete(PENDING_PRINCIPAL_KEY)
+        end
+
+        # The queued sign-in runs inside the probed request, so it is marked
+        # as identity setup (Identity.establishing): nothing it or the
+        # application's own after_set_user hooks do -- a Devise :trackable
+        # UPDATE, say -- is evidence about the probed route. If it raises,
+        # the route never runs, and EstablishmentError says so rather than
+        # letting the failure pass for the route's own exception.
         def install_hook!
           return if @installed
 
@@ -57,9 +73,18 @@ module Karst
             pending = Karst::ExecutionContext.delete(PENDING_PRINCIPAL_KEY)
             next unless pending
 
-            principal, scope = pending
+            apply_pending(proxy, *pending)
+          end
+        end
+
+        private
+
+        def apply_pending(proxy, principal, scope)
+          Karst::Identity.establishing do
             scope ? proxy.set_user(principal, scope: scope) : proxy.set_user(principal)
           end
+        rescue StandardError => e
+          raise Karst::Identity::EstablishmentError, "#{e.class}: #{e.message}"
         end
       end