karst 0.1.0

data/lib/karst/configuration.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "access/principal_source"
+require_relative "access/approved_populations"
+require_relative "access/selected_principal_sources"
+require_relative "identity/devise_support"
+
+module Karst
+  # Raised when an initializer sets a configuration option Karst has removed.
+  # A NoMethodError subclass, so a removed option fails exactly like an
+  # ordinary typo would -- but with a message naming the removal and what
+  # replaced it. Karst never reinterprets a removed option as something else.
+  class RemovedConfiguration < NoMethodError; end
+
+  # Process-level settings that control Karst's implemented behavior.
+  #
+  # An ordinary application sets none of this. A single-model Devise app is
+  # inferred outright, candidate populations are approved locally at
+  # /karst/populations rather than written here, and every limit below
+  # already has a bounded default. `enabled` is not normal configuration
+  # either -- it is an off switch for exceptional cases (a shared
+  # development environment, a CI job that boots Rails but must never run
+  # 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.
+  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,
+                  :assume_browser_identity, :clear_browser_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.
+    #
+    # configured_principal_sources is internal: what the application
+    # explicitly configured, before Devise inference or local approvals are
+    # folded in. Read only by Karst::Identity to distinguish "configured"
+    # from "inferred"; not part of the documented configuration surface.
+    attr_reader :principal_populations, :access_sweep_limit, :population_retry_limit,
+                :principal_candidate_pool_size, :usable_access_outcome, :configured_principal_sources
+
+    # What Karst treats as "this user can use the page": an observed 200 with
+    # no contrary evidence. Older/custom outcome-like values may expose only
+    # a status; an absent optional evidence field means Karst did not observe
+    # that evidence, just as an explicit nil does, and must not make the
+    # policy itself crash.
+    DEFAULT_USABLE_ACCESS_OUTCOME = lambda do |outcome|
+      unobserved = ->(attribute) { !outcome.respond_to?(attribute) || outcome.public_send(attribute).nil? }
+      outcome.status == 200 && unobserved.call(:exception_class) && unobserved.call(:halted_callback)
+    end
+
+    MAX_ACCESS_SWEEP_LIMIT = 100
+
+    # How many records a single candidate population may contribute when
+    # Karst automatically retries it after an ordinary sample found nothing
+    # usable (see Karst::Access::Search). Kept deliberately small: the point
+    # of a population retry is to answer "does this population reach the
+    # behavior at all," which one or two records already settle -- not to
+    # survey the population. The total number of extra requests a retry may
+    # issue is bounded separately, by access_sweep_limit, so adding
+    # populations can never make an analysis cost more than roughly twice an
+    # ordinary sweep.
+    MAX_POPULATION_RETRY_LIMIT = 10
+
+    # Conservative hard ceiling on how many recent principals a
+    # representative-sampling candidate pool may ever cover. This bounds the
+    # cost of the one bounded pool query the sampler issues, independent of
+    # how large the underlying table actually is.
+    MAX_PRINCIPAL_CANDIDATE_POOL_SIZE = 10_000
+
+    # Options Karst used to expose, mapped to what an application should do
+    # instead. Karst is pre-1.0 and prefers a clean surface to accumulated
+    # accidental complexity -- but a removed option must say so out loud
+    # rather than be silently ignored or quietly reinterpreted.
+    REMOVED = {
+      buffer_size: "runtime SQL capture was removed; Karst reports evidence from the requests it " \
+                   "actually runs, and no longer keeps a process-wide sql.active_record buffer",
+      principal_dimensions: "sampling states are derived from the schema automatically; there is " \
+                            "nothing to declare, and rare users are reached through candidate " \
+                            "populations approved at /karst/populations",
+      artifact_source: "artifact scenarios were removed; Karst analyzes routes, not record sweeps",
+      access_scenario: "artifact scenarios were removed; Karst analyzes routes, not record sweeps"
+    }.freeze
+
+    def initialize
+      @enabled = defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.development? || Rails.env.test? : false
+      @access_sweep_limit = 25
+      @principal_candidate_pool_size = 1_000
+      @population_retry_limit = 3
+      @usable_access_outcome = DEFAULT_USABLE_ACCESS_OUTCOME
+      @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) }
+    end
+
+    # An application-authored hint about meaningful candidate populations for
+    # whatever config.principals returns -- a Hash of name => zero-argument
+    # callable, each expected to return an ActiveRecord::Relation scoped to
+    # that same model, for example:
+    #
+    #   config.principal_populations = {
+    #     system_admins: -> { User.system_admins },
+    #     auditors: -> { User.auditors }
+    #   }
+    #
+    # This is the committed-to-source form of what /karst/populations already
+    # captures locally, and is needed only where machine-local approval state
+    # is deliberately not consulted (CI) or where populations should be
+    # reviewable code. Karst never infers that a population grants access or
+    # produces any UI state; it only tries records from it (see
+    # Karst::Access::PrincipalSampler/CandidatePopulation). nil/{} (the
+    # default) considers no configured populations at all. Karst does not
+    # attempt to verify that a callable's body is a "real" Rails named scope
+    # -- it only checks what calling it actually returns. Applications
+    # representing identity as more than one model configure populations per
+    # source instead (see config.principal_sources).
+    def principal_populations=(populations)
+      @principal_populations = Access::PrincipalSource.normalize_populations(:default, populations)
+    end
+
+    def principal_sources=(sources)
+      @configured_principal_sources = Access::PrincipalSource.normalize(sources)
+    end
+
+    # The effective, normalized principal population(s) Karst may sample
+    # from or resolve into: explicit config.principal_sources when
+    # configured, otherwise a bare config.principals (plus any
+    # config.principal_populations) wrapped as one implicit :default source,
+    # otherwise -- when neither is configured -- one inferred Devise model
+    # wrapped the same way (see Karst::Identity::DeviseSupport), otherwise --
+    # with several Devise models and nothing explicit -- whatever a
+    # developer has locally selected at /karst (see
+    # Access::SelectedPrincipalSources, one source per selected model, each
+    # keyed by its own Devise scope), or nil when none of those apply. A
+    # Hash of Symbol => PrincipalSource.
+    #
+    # This is also where locally approved discovered populations (see
+    # Karst::Access::ApprovedPopulations) join the effective configuration,
+    # after each source's own explicitly configured populations. Every
+    # adapter -- the panel, `bin/rails karst:verify`, the MCP verify_access
+    # tool -- reads this one method, so none of them knows or can diverge on
+    # 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)
+    end
+
+    def access_sweep_limit=(value)
+      unless value.is_a?(Integer) && value.positive? && value <= MAX_ACCESS_SWEEP_LIMIT
+        raise ArgumentError, "access_sweep_limit must be between 1 and #{MAX_ACCESS_SWEEP_LIMIT}"
+      end
+
+      @access_sweep_limit = value
+    end
+
+    def principal_candidate_pool_size=(value)
+      unless value.is_a?(Integer) && value.positive? && value <= MAX_PRINCIPAL_CANDIDATE_POOL_SIZE
+        raise ArgumentError,
+              "principal_candidate_pool_size must be between 1 and #{MAX_PRINCIPAL_CANDIDATE_POOL_SIZE}"
+      end
+
+      @principal_candidate_pool_size = value
+    end
+
+    def population_retry_limit=(value)
+      unless value.is_a?(Integer) && value.positive? && value <= MAX_POPULATION_RETRY_LIMIT
+        raise ArgumentError, "population_retry_limit must be between 1 and #{MAX_POPULATION_RETRY_LIMIT}"
+      end
+
+      @population_retry_limit = value
+    end
+
+    def usable_access_outcome=(policy)
+      raise ArgumentError, "usable_access_outcome must be callable" unless policy.respond_to?(:call)
+
+      @usable_access_outcome = policy
+    end
+
+    private
+
+    # A removed option fails loudly and says what replaced it, rather than
+    # reaching Ruby's generic "undefined method" and leaving a developer to
+    # guess whether Karst renamed, moved, or silently ignored it.
+    def method_missing(name, *)
+      removal = REMOVED[name.to_s.delete_suffix("=").to_sym]
+      return super unless removal
+
+      raise RemovedConfiguration,
+            "config.#{name.to_s.delete_suffix('=')} was removed from Karst: #{removal}"
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      REMOVED.key?(name.to_s.delete_suffix("=").to_sym) || super
+    end
+
+    def configured_or_inferred_sources
+      return @configured_principal_sources if @configured_principal_sources
+      return default_principal_source(@principals) if @principals
+
+      inferred = Identity::DeviseSupport.unambiguous_mapping
+      return default_principal_source(-> { inferred.model.all }) if inferred
+
+      # Several Devise models and nothing explicit: fall back to whatever a
+      # developer has locally selected at /karst (see
+      # Access::SelectedPrincipalSources), still nil when nothing has been
+      # selected or every selection has gone stale -- Karst never guesses.
+      Access::SelectedPrincipalSources.sources
+    end
+
+    def default_principal_source(records)
+      { default: Access::PrincipalSource.new(name: :default, records: records,
+                                             populations: @principal_populations) }
+    end
+  end
+end

data/lib/karst/execution_context.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+begin
+  require "active_support/isolated_execution_state"
+rescue LoadError
+  # Rails 6.1 does not ship this file (added in Rails 7.0). The thread-local
+  # fallback below (Karst::ExecutionContext::ThreadLocalStore) stands in for
+  # it on that series.
+end
+
+module Karst
+  # Request-local correlation storage used by the page badge and the RSpec
+  # scenario observer to carry evidence from a notification callback (fired
+  # nested inside a Rack call or an RSpec example) back out to the code that
+  # reads it, without a global mutable variable that would let concurrent
+  # requests or examples cross-contaminate each other.
+  #
+  # Modern Rails already solves exactly this with
+  # ActiveSupport::IsolatedExecutionState, so Karst simply delegates to it
+  # when present. Rails 6.1 does not provide that API, so Karst falls back to
+  # ThreadLocalStore, a plain per-Thread Hash reached through
+  # Thread#thread_variable_get/set -- never Thread#[]/[]=, which are
+  # fiber-local and would silently miss context under a Fiber scheduler.
+  # This mirrors ActiveSupport::IsolatedExecutionState's own default :thread
+  # isolation level: storage is shared by every Fiber running on one OS
+  # thread, not isolated per Fiber. Karst's own usage (one badge or spec
+  # correlation captured and read back within a single synchronous
+  # request/example) never spans multiple concurrently-scheduled Fibers, so
+  # this fallback has no observable effect on Karst's supported behavior. It
+  # is documented here so a future caller does not assume Fiber isolation
+  # this fallback cannot provide.
+  module ExecutionContext
+    # Deliberately its own class, rather than inlined into
+    # ExecutionContext's own singleton methods, so its behavior is directly
+    # testable on every supported Ruby regardless of which backend
+    # ExecutionContext itself selects in a given process.
+    class ThreadLocalStore
+      THREAD_VARIABLE = :karst_execution_context
+      private_constant :THREAD_VARIABLE
+
+      def [](key)
+        store[key]
+      end
+
+      def []=(key, value)
+        store[key] = value
+      end
+
+      def delete(key)
+        store.delete(key)
+      end
+
+      private
+
+      def store
+        Thread.current.thread_variable_get(THREAD_VARIABLE) ||
+          Thread.current.thread_variable_set(THREAD_VARIABLE, {})
+      end
+    end
+    private_constant :ThreadLocalStore
+
+    BACKEND = if defined?(ActiveSupport::IsolatedExecutionState)
+                ActiveSupport::IsolatedExecutionState
+              else
+                ThreadLocalStore.new
+              end
+    private_constant :BACKEND
+
+    class << self
+      def [](key)
+        BACKEND[key]
+      end
+
+      def []=(key, value)
+        BACKEND[key] = value
+      end
+
+      def delete(key)
+        BACKEND.delete(key)
+      end
+    end
+  end
+end

data/lib/karst/identity/devise_support.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Karst
+  module Identity
+    # Reads Devise's own routing-registered mapping metadata to determine
+    # which model(s) Devise protects and which Warden scope each one uses --
+    # never by scanning ObjectSpace, guessing from a model's name (User,
+    # Account, ...), or inferring from column names (encrypted_password,
+    # email, ...).
+    #
+    # `Devise.mappings` is populated by `devise_for` in config/routes.rb (the
+    # same metadata Devise itself relies on for `authenticate_user!`,
+    # `current_user`, and friends), so by the time a real request reaches
+    # Karst, every conventional Devise application already has it populated.
+    module DeviseSupport
+      # One Devise-registered model/Warden-scope pair, straight from
+      # Devise's own mapping -- never guessed.
+      Mapping = Value.define(:model, :scope)
+
+      class << self
+        # Returns the sole authentication key Devise declares for +model+.
+        # Multiple keys are intentionally treated as ambiguous: Karst cannot
+        # know which value is the useful login identity (or whether the
+        # combination itself is sensitive).
+        def authentication_key_for(model)
+          mapping = mapping_for(model)
+          return nil unless mapping && model.respond_to?(:authentication_keys)
+
+          keys = Array(model.authentication_keys).filter_map { |key| normalized_key(key) }.uniq
+          keys.first if keys.size == 1
+        rescue StandardError
+          nil
+        end
+
+        def available?
+          !!(defined?(Devise) && Devise.respond_to?(:mappings))
+        end
+
+        # Every Devise-registered mapping currently known to the framework.
+        # Empty when Devise is unavailable or has registered nothing yet.
+        def mappings
+          return [] unless available?
+
+          Devise.mappings.values.filter_map { |mapping| build(mapping) }
+        rescue StandardError
+          []
+        end
+
+        # The single unambiguous Devise mapping, or nil when there are zero
+        # or more than one -- multiple Devise models are a deliberate
+        # ambiguity boundary Karst never guesses across.
+        def unambiguous_mapping
+          candidates = mappings
+          candidates.first if candidates.size == 1
+        end
+
+        # The Devise mapping for one specific model class (including a
+        # subclass of a mapped model, e.g. STI), if Devise itself registers
+        # it. Used once a principal model is already known -- from an actual
+        # principal instance or an explicitly configured source -- so this
+        # never has to guess which of several Devise models is intended.
+        def mapping_for(model)
+          return nil unless model.is_a?(Class)
+
+          mappings.find { |mapping| model <= mapping.model }
+        end
+
+        private
+
+        def normalized_key(key)
+          key.to_sym
+        rescue StandardError
+          nil
+        end
+
+        def build(devise_mapping)
+          model = devise_mapping.to if devise_mapping.respond_to?(:to)
+          scope = devise_mapping.name if devise_mapping.respond_to?(:name)
+          return nil unless model.is_a?(Class) && scope
+
+          Mapping.new(model: model, scope: scope)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/karst/identity/warden_adapter.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "../execution_context"
+
+module Karst
+  module Identity
+    # Optional convenience for a request-like object whose Rack environment
+    # already contains a Warden proxy. Warden cannot be bootstrapped safely
+    # from a bare ActionDispatch::Integration::Session, so applications using
+    # those sessions should configure explicit hooks (usually test endpoints).
+    #
+    # `scope:` is the Warden/Devise scope (e.g. `:user`, `:admin`) this
+    # adapter operates under. When known (see DeviseSupport), it is always
+    # passed explicitly rather than relying on Warden's own default scope --
+    # a Devise app almost always protects routes with a specific scope, and
+    # guessing wrong would silently authenticate under the wrong one. When
+    # nil, `set_user`/`logout` are called without a scope, matching Warden's
+    # own default behavior for a plain, non-Devise Warden setup.
+    class WardenAdapter
+      # Karst::Identity.with calls #assume before the caller's own block ever
+      # issues a request, so no env["warden"] proxy can exist yet -- Warden
+      # only builds one inside Warden::Manager#call, once a request actually
+      # reaches it (see Access::ProbeApplication). #assume therefore queues
+      # the principal here instead of reaching for a proxy that cannot exist,
+      # and .install_hook! below applies it the moment this exact thread's
+      # own probe request reaches Warden -- the same queue-for-next-request
+      # idiom Warden::Test::Helpers#login_as and
+      # Devise::Test::IntegrationHelpers#sign_in use for the identical
+      # problem in integration tests. Karst uses its own thread-local
+      # ExecutionContext instead of Warden's own global Test::Helpers queue,
+      # so this stays scoped to the exact thread that queued it -- a
+      # concurrent unrelated request on another thread of a real development
+      # server never observes it.
+      PENDING_PRINCIPAL_KEY = :karst_warden_pending_principal
+      private_constant :PENDING_PRINCIPAL_KEY
+
+      class << self
+        # Registered once per process (Warden::Hooks callbacks are
+        # class-level, so this necessarily runs for every Warden::Manager
+        # instance, including the host application's own) and is a no-op
+        # unless this exact thread has a principal queued. The real Warden
+        # gem always provides Warden::Manager.on_request (Warden::Hooks is
+        # core, not an extra); the guard exists only so a minimal
+        # Warden::Manager stand-in (a bare stub Class, as several existing
+        # specs use to exercise ambiguous-Devise-setup paths that never
+        # reach this code) can't crash Karst with a NoMethodError instead of
+        # deferral simply staying unavailable, same as before this existed.
+        def hook_installable?
+          defined?(Warden::Manager) && Warden::Manager.respond_to?(:on_request)
+        end
+
+        def install_hook!
+          return if @installed
+
+          @installed = true
+          Warden::Manager.on_request do |proxy|
+            pending = Karst::ExecutionContext.delete(PENDING_PRINCIPAL_KEY)
+            next unless pending
+
+            principal, scope = pending
+            scope ? proxy.set_user(principal, scope: scope) : proxy.set_user(principal)
+          end
+        end
+      end
+
+      attr_reader :scope
+
+      def initialize(scope: nil)
+        @scope = scope
+      end
+
+      def assume(session, principal)
+        proxy = existing_proxy(session)
+        return apply(proxy, principal) if proxy
+        return queue_for_next_request(principal) if deferrable?(session)
+
+        raise Unavailable, "the session has no initialized Warden proxy; configure identity hooks"
+      end
+
+      def clear(session)
+        proxy = proxy_for(session)
+        @scope ? proxy.logout(@scope) : proxy.logout
+      ensure
+        Karst::ExecutionContext.delete(PENDING_PRINCIPAL_KEY)
+      end
+
+      private
+
+      def apply(proxy, principal)
+        @scope ? proxy.set_user(principal, scope: @scope) : proxy.set_user(principal)
+      end
+
+      # Deferral only ever helps a real pre-dispatch integration session --
+      # something that will itself later be routed through Warden::Manager,
+      # letting .install_hook! consume the queued principal when that
+      # happens. A bare Hash (the shape every other caller in this codebase,
+      # and custom identity hooks, already use to carry an env["warden"] key
+      # directly) has no such future dispatch to defer to, so queuing for it
+      # would silently do nothing forever -- raising immediately, as before,
+      # is the correct and only honest outcome there.
+      def deferrable?(session)
+        !session.is_a?(Hash) && session.respond_to?(:request) && self.class.hook_installable?
+      end
+
+      def queue_for_next_request(principal)
+        self.class.install_hook!
+        Karst::ExecutionContext[PENDING_PRINCIPAL_KEY] = [principal, @scope]
+      end
+
+      def proxy_for(session)
+        existing_proxy(session) ||
+          (raise Unavailable, "the session has no initialized Warden proxy; configure identity hooks")
+      end
+
+      def existing_proxy(session)
+        env = rack_env(session)
+        proxy = env && env["warden"]
+        proxy if proxy.respond_to?(:set_user) && proxy.respond_to?(:logout)
+      end
+
+      def rack_env(session)
+        return session if session.is_a?(Hash)
+        return session.env if session.respond_to?(:env)
+        return session.request.env if session.respond_to?(:request) && session.request.respond_to?(:env)
+
+        nil
+      end
+    end
+  end
+end