karst 0.1.0

data/lib/karst/access/principal_sampler.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "sweep"
+require_relative "sensitive_attribute_names"
+
+module Karst
+  module Access
+    # Selects a small candidate set without ever scanning the full principal
+    # relation: one bounded recent pool, stratified in memory by coarse
+    # states derived from the schema itself -- boolean and enum columns,
+    # nullable-foreign-key presence, and low-cardinality scalars, minus
+    # anything PII- or tenancy-shaped. Nothing here is configurable: an
+    # application that needs a specific rare user reaches it through a
+    # candidate population (Karst::Access::CandidatePopulation), which is
+    # named, reportable evidence, rather than by tuning how the ordinary
+    # sample spreads.
+    #
+    # Application-authored *populations* deliberately do not live here. They
+    # are a second search stage owned by Karst::Access::Search, which runs
+    # them only after an ordinary sample observes no usable outcome -- a
+    # population folded into this sample would silently become part of an
+    # ordinary-looking result, and Karst could never report the stronger,
+    # true story: "the ordinary sample failed; then system_admins reached
+    # it." This class only selects candidates. Access::Sweep remains the
+    # sole source of behavioral evidence.
+    # rubocop:disable Metrics/ClassLength
+    class PrincipalSampler
+      class UnsupportedPrimaryKey < Error; end
+
+      CARDINALITY_CUTOFF = 10
+      MAX_DIMENSIONS = 8
+      TENANCY_FK_TOKENS = %w[tenant account organization org company workspace team customer client shop].freeze
+      ALLOWED_SCALAR_TYPES = %i[integer bigint string].freeze
+
+      Candidate = Value.define(:principal, :reasons)
+      Result = Value.define(:principals, :candidates, :strategy, :queries, :candidate_pool_size)
+      DimensionValue = Struct.new(:reason, :matcher, keyword_init: true)
+      private_constant :DimensionValue
+
+      # Exactly one bounded recent-pool query. Every stratification decision
+      # after that is made in memory over that pool.
+      def self.query_budget(_limit = nil)
+        1
+      end
+
+      def initialize(source:, limit: Karst.config.access_sweep_limit,
+                     pool_size: Karst.config.principal_candidate_pool_size)
+        @source = source
+        @limit = limit
+        @pool_size = pool_size
+        @queries = 0
+        @query_budget = self.class.query_budget
+      end
+
+      def call
+        relation = active_record_relation
+        return fallback_sample unless relation
+
+        representative_sample(relation)
+      end
+
+      def self.representative_capable?(source)
+        return true if defined?(ActiveRecord::Relation) && source.is_a?(ActiveRecord::Relation)
+
+        defined?(ActiveRecord::Base) && source.is_a?(Class) && source < ActiveRecord::Base
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def active_record_relation
+        return @source if defined?(ActiveRecord::Relation) && @source.is_a?(ActiveRecord::Relation)
+
+        @source.all if defined?(ActiveRecord::Base) && @source.is_a?(Class) && @source < ActiveRecord::Base
+      end
+
+      def fallback_sample
+        principals = @source.each.lazy.take(@limit).to_a
+        candidates = principals.map { |principal| Candidate.new(principal: principal, reasons: []) }
+        Result.new(principals: principals, candidates: candidates, strategy: :first_n, queries: 0,
+                   candidate_pool_size: nil)
+      end
+
+      def representative_sample(relation)
+        klass = relation.klass
+        primary_key = single_primary_key!(klass)
+        pool = recent_pool(relation, klass, primary_key)
+        selected = {}
+
+        apply_dimensions(pool, primary_key, generic_dimensions(pool, klass), selected)
+        fill_remaining(pool, primary_key, selected)
+
+        candidates = selected.values
+        Result.new(principals: candidates.map(&:principal), candidates: candidates,
+                   strategy: :representative, queries: @queries, candidate_pool_size: @pool_size)
+      end
+
+      def recent_pool(relation, klass, primary_key)
+        return [] unless query_allowed?
+
+        order = klass.columns_hash.key?("created_at") ? { created_at: :desc } : { primary_key => :desc }
+        @queries += 1
+        relation.reorder(order).limit(@pool_size).to_a
+      end
+
+      def single_primary_key!(klass)
+        primary_key = klass.primary_key
+        return primary_key if primary_key.is_a?(String)
+
+        raise UnsupportedPrimaryKey,
+              "Karst::Access::PrincipalSampler requires #{klass.name} to have a single-column primary key " \
+              "(got #{primary_key.inspect}); pass an already-materialized Array/Enumerable of principals " \
+              "instead to use bounded-first sampling"
+      end
+
+      def query_allowed?
+        @queries < @query_budget
+      end
+
+      def generic_dimensions(pool, klass)
+        candidate_columns(klass).first(MAX_DIMENSIONS).filter_map do |column|
+          values = generic_values(pool, klass, column)
+          next unless values
+
+          values
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def generic_values(pool, klass, column)
+        if enum_mapping(klass, column)
+          enum_mapping(klass, column).keys.sort.map do |value|
+            equality_value(column, value, value)
+          end
+        elsif column.type == :boolean
+          [true, false].map { |value| equality_value(column, value, value.inspect) }
+        elsif nullable_foreign_key?(klass, column)
+          [true, false].map { |present| foreign_key_value(column, present) }
+        elsif ALLOWED_SCALAR_TYPES.include?(column.type)
+          scalar_values(pool, column)
+        end
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def scalar_values(pool, column)
+        values = pool.map { |record| record.public_send(column.name) }.uniq
+        return unless values.size.between?(2, CARDINALITY_CUTOFF)
+
+        values.sort_by(&:to_s).map { |value| equality_value(column, value, format_value(value)) }
+      end
+
+      # Booleans/nil render as `true`/`false`/`nil`; everything else (a role
+      # string, an enum key, a plan tier) renders plainly -- so a `role`
+      # column reads `role=local_admin`, not the quoted `role="local_admin"`
+      # a blind #inspect would produce.
+      def format_value(value)
+        case value
+        when true, false, nil then value.inspect
+        else value.to_s
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def apply_dimensions(pool, primary_key, dimensions, selected)
+        queues = dimensions.map(&:dup)
+        loop do
+          progressed = false
+          queues.each do |queue|
+            value = queue.shift
+            next unless value
+
+            progressed = true
+            record = pool.find { |candidate| value.matcher.call(candidate) }
+            next unless record
+
+            id = record.public_send(primary_key)
+            existing = selected[id]
+            reasons = existing ? (existing.reasons + [value.reason]).uniq : [value.reason]
+            selected[id] = Candidate.new(principal: record, reasons: reasons)
+            break if selected.size >= @limit
+          end
+          break if selected.size >= @limit || !progressed
+        end
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def fill_remaining(pool, primary_key, selected)
+        pool.each do |record|
+          break if selected.size >= @limit
+
+          id = record.public_send(primary_key)
+          selected[id] ||= Candidate.new(principal: record, reasons: [])
+        end
+      end
+
+      def candidate_columns(klass)
+        klass.columns_hash.values.reject do |column|
+          column.name == klass.primary_key || SensitiveAttributeNames.match?(column.name) ||
+            encrypted_attribute?(klass, column) || tenancy_foreign_key?(column)
+        end
+      end
+
+      def encrypted_attribute?(klass, column)
+        klass.respond_to?(:encrypted_attributes) && klass.encrypted_attributes&.include?(column.name.to_sym)
+      end
+
+      def tenancy_foreign_key?(column)
+        column.name.end_with?("_id") &&
+          column.name.downcase.split("_").any? { |token| TENANCY_FK_TOKENS.include?(token) }
+      end
+
+      def nullable_foreign_key?(klass, column)
+        column.name.end_with?("_id") && column.name != klass.primary_key && column.null
+      end
+
+      def enum_mapping(klass, column)
+        klass.defined_enums[column.name] if klass.respond_to?(:defined_enums)
+      end
+
+      def equality_value(column, value, label)
+        dimension_value("#{column.name}=#{label}") do |record|
+          record.public_send(column.name) == value
+        end
+      end
+
+      def foreign_key_value(column, present)
+        label = present ? "present" : "absent"
+        dimension_value("#{column.name} #{label}") do |record|
+          record.public_send(column.name).nil? != present
+        end
+      end
+
+      def dimension_value(reason, &matcher)
+        DimensionValue.new(reason: reason, matcher: matcher)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/karst/access/principal_selection.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "principal_sampler"
+
+module Karst
+  module Access
+    # Runs Karst::Access::PrincipalSampler independently per configured
+    # Karst::Access::PrincipalSource -- never materializing multiple sources
+    # together (no `Author.all.to_a + Reader.all.to_a`) -- and allocates the
+    # combined candidates within one overall `limit`. The single-source case
+    # (including the implicit legacy `:default` source Configuration builds
+    # from a bare `config.principals`) behaves identically to calling
+    # PrincipalSampler directly: this class only changes behavior once more
+    # than one source is actually configured.
+    #
+    # Allocation policy (deliberately simple, not a general-purpose
+    # scheduler): every non-empty source is guaranteed at least one
+    # candidate, then remaining room is filled round-robin across sources,
+    # each contributing its own candidates in the order PrincipalSampler
+    # already prioritizes them (dimension-covering candidates before plain
+    # fill). One source running out never blocks another from filling the
+    # rest of the budget.
+    class PrincipalSelection
+      Result = Value.define(:principals, :candidates, :queries, :candidate_pool_size)
+
+      def initialize(sources:, limit: Karst.config.access_sweep_limit,
+                     pool_size: Karst.config.principal_candidate_pool_size)
+        @sources = sources || {}
+        @limit = limit
+        @pool_size = pool_size
+      end
+
+      def call
+        return empty_result if @sources.empty?
+
+        per_source = sample_each_source
+        build_result(per_source, allocate(per_source))
+      end
+
+      private
+
+      def sample_each_source
+        @sources.each_with_object({}) do |(name, source), memo|
+          memo[name] = PrincipalSampler.new(source: source.evaluate, limit: @limit, pool_size: @pool_size).call
+        end
+      end
+
+      def allocate(per_source)
+        names = per_source.keys
+        queues = per_source.transform_values { |result| result.candidates.dup }
+        selected = []
+        index = 0
+        until selected.size >= @limit || queues.values.all?(&:empty?)
+          take_one(queues, names[index % names.size], selected)
+          index += 1
+        end
+        selected
+      end
+
+      def take_one(queues, name, selected)
+        queue = queues.fetch(name)
+        selected << [name, queue.shift] unless queue.empty?
+      end
+
+      def build_result(per_source, allocated)
+        multi_source = per_source.size > 1
+        candidates = allocated.map { |name, candidate| multi_source ? tag_source(candidate, name) : candidate }
+
+        Result.new(
+          principals: candidates.map(&:principal), candidates: candidates,
+          queries: per_source.values.sum(&:queries), candidate_pool_size: combined_pool_size(per_source)
+        )
+      end
+
+      def tag_source(candidate, name)
+        PrincipalSampler::Candidate.new(principal: candidate.principal, reasons: candidate.reasons + ["source=#{name}"])
+      end
+
+      def combined_pool_size(per_source)
+        sizes = per_source.values.filter_map(&:candidate_pool_size)
+        sizes.empty? ? nil : sizes.sum
+      end
+
+      def empty_result
+        Result.new(principals: [], candidates: [], queries: 0, candidate_pool_size: nil)
+      end
+    end
+  end
+end

data/lib/karst/access/principal_source.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Karst
+  module Access
+    # One allowed principal population Karst may sample from or resolve
+    # into -- "which records may Karst consider at all," a different
+    # question from Karst::Access::CandidatePopulation ("which
+    # application-authored relation, within this source, is worth trying
+    # first").
+    #
+    # `records` is a callable Karst evaluates lazily, exactly like a bare
+    # `config.principals` -- never enumerated, sampled, or materialized just
+    # by building a PrincipalSource. A single config.principals (plus any
+    # config.principal_populations) is normalized into one implicit
+    # `:default` PrincipalSource internally (see
+    # Karst::Configuration#principal_sources), so every downstream consumer
+    # (PrincipalSelection, Identity.resolve, the panel) only ever has to
+    # handle "one or more sources," never a separate single-source case.
+    class PrincipalSource
+      attr_reader :name, :records, :populations
+
+      def initialize(name:, records:, populations: {})
+        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)
+      end
+
+      # Evaluates the configured records callable. Never enumerates or
+      # queries on its own -- for an Active Record source this only builds a
+      # Relation, exactly like Karst::Identity.principals already did for
+      # the single-source case.
+      def evaluate
+        records.call
+      end
+
+      # The Active Record class this source's records ultimately belong to,
+      # or nil for a source whose evaluated records are not an
+      # ActiveRecord::Relation/Class (a plain Array/Enumerable source, or a
+      # callable that raises). Only ever builds a Relation to read its
+      # #klass -- never queries a row. Used to match a
+      # Karst::Access::PopulationDiscovery-discovered model against an
+      # already-configured principal source, and by the panel's guided
+      # population retry.
+      def record_klass
+        evaluated = evaluate
+        return evaluated if defined?(ActiveRecord::Base) && evaluated.is_a?(Class) && evaluated < ActiveRecord::Base
+        return evaluated.klass if defined?(ActiveRecord::Relation) && evaluated.is_a?(ActiveRecord::Relation)
+
+        nil
+      rescue StandardError
+        nil
+      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,
+      # so nothing downstream has to know an approval workflow exists.
+      # Explicit configuration wins outright: a name this source already
+      # configures keeps its configured callable, and configured populations
+      # keep their position ahead of appended ones.
+      def with_populations(extra)
+        return self if extra.nil? || extra.empty?
+
+        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))
+      end
+
+      # Accepts a raw Hash of name => (callable, or {records:,
+      # populations:}) -- the shape config.principal_sources= receives.
+      def self.normalize(sources)
+        return nil if sources.nil?
+        raise ArgumentError, "principal_sources must be a Hash of name => records/{records:, populations:}" unless
+          sources.is_a?(Hash)
+
+        sources.each_with_object({}) do |(name, spec), normalized|
+          source = spec.is_a?(PrincipalSource) ? spec : from_spec(name, spec)
+          normalized[source.name] = source
+        end
+      end
+
+      SPEC_KEYS = %w[records populations].freeze
+      private_constant :SPEC_KEYS
+
+      def self.from_spec(name, spec)
+        return new(name: name, records: spec) if spec.respond_to?(:call)
+
+        unless spec.is_a?(Hash)
+          raise ArgumentError, "principal source #{name.inspect} must be callable or a Hash with :records"
+        end
+
+        reject_unknown_keys!(name, spec)
+        new(name: name, records: fetch_any(spec, :records), populations: fetch_any(spec, :populations) || {})
+      end
+
+      # An unrecognized key is refused rather than ignored. `dimensions:` in
+      # particular used to be meaningful here; a source spec that still
+      # carries one must fail loudly instead of quietly sampling differently
+      # than its author configured.
+      def self.reject_unknown_keys!(name, spec)
+        unknown = spec.keys.map(&:to_s) - SPEC_KEYS
+        return if unknown.empty?
+
+        detail = if unknown.include?("dimensions")
+                   "; :dimensions was removed -- sampling states are derived from the schema automatically"
+                 else
+                   ""
+                 end
+        raise ArgumentError,
+              "principal source #{name.inspect} got unknown key(s) #{unknown.join(', ')}; " \
+              "supported keys are :records and :populations#{detail}"
+      end
+      private_class_method :reject_unknown_keys!
+
+      # A configured population is a Hash of name => zero-argument callable
+      # expected to return an ActiveRecord::Relation scoped to this same
+      # source -- see Karst::Access::CandidatePopulation. Deliberately kept
+      # as raw callables here, not wrapped into CandidatePopulation
+      # instances: a CandidatePopulation represents one already-*resolved*
+      # (queried) population, which only happens once PrincipalSampler
+      # actually runs, never at configuration time.
+      def self.normalize_populations(source_name, populations)
+        return {} if populations.nil?
+
+        valid = populations.is_a?(Hash) && populations.all? { |n, c| n.is_a?(Symbol) && c.respond_to?(:call) }
+        unless valid
+          raise ArgumentError,
+                "principal source #{source_name.inspect} populations must be a Hash of Symbol => callable"
+        end
+
+        populations
+      end
+
+      def self.fetch_any(hash, key)
+        hash.fetch(key) { hash[key.to_s] }
+      end
+      private_class_method :fetch_any
+    end
+  end
+end

data/lib/karst/access/principal_source_selection.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../value"
+
+module Karst
+  module Access
+    # The local, machine-scoped record of which ambiguous Devise model(s) a
+    # developer has explicitly told Karst to test (see
+    # Karst::Access::SelectedPrincipalSources for how this is turned back
+    # into runnable Karst::Access::PrincipalSource objects, revalidated
+    # against Karst::Identity::DeviseSupport's own current metadata on every
+    # read).
+    #
+    # Deliberately *data*, never code: an entry is a bare model name and
+    # nothing else -- never a scope, a class, or any executable Ruby. Karst
+    # never constantizes a stored name; it is only ever compared, as a
+    # string, against what Devise.mappings currently reports. This is the
+    # same never-trust-the-file posture Karst::Access::PopulationApprovals
+    # uses for candidate populations, applied one layer earlier: to *which
+    # models* Karst may consider at all, not what it may sample from within
+    # one already-known model.
+    #
+    # Stored under the host application's `tmp/` (`tmp/karst/`) for the same
+    # reason approved populations are: machine-local, disposable,
+    # git-ignored, reset by deleting the file, and consulted only in
+    # development/test (see Karst::Access::ApprovedPopulations.local_environment?,
+    # reused as-is by Karst::Access::SelectedPrincipalSources -- this is the
+    # same local-preference mechanism, not a parallel one).
+    #
+    # Every read fails closed, exactly like PopulationApprovals: a file that
+    # is unreadable, is not JSON, is not the expected document shape, carries
+    # an unknown schema version, or holds a single entry that is not a
+    # plausible constant name selects nothing at all.
+    module PrincipalSourceSelection
+      SCHEMA_VERSION = 1
+
+      RELATIVE_PATH = File.join("tmp", "karst", "principal_source_selection.json")
+
+      # Matched only against Karst::Identity::DeviseSupport.mappings' own
+      # model names -- a stored name is never constantized and never used to
+      # look up an arbitrary constant.
+      MODEL_NAME = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+
+      # A generous bound no realistic application approaches -- exists only
+      # so a corrupted or maliciously grown document cannot turn every
+      # principal source resolution into unbounded work.
+      MAX_ENTRIES = 50
+
+      Record = Value.define(:model_names, :error) do
+        def selected?(model_name)
+          model_names.include?(model_name.to_s)
+        end
+      end
+
+      class << self
+        def path
+          File.join(root, RELATIVE_PATH)
+        end
+
+        # The path as a developer should see it: relative to the application
+        # root, since that is where they will go looking for (or delete) it.
+        def display_path
+          RELATIVE_PATH
+        end
+
+        def load
+          document = JSON.parse(File.read(path))
+          parse(document)
+        rescue Errno::ENOENT
+          empty
+        rescue JSON::ParserError
+          failed("could not be read as JSON")
+        rescue StandardError => e
+          failed("could not be read (#{e.class})")
+        end
+
+        # Replaces the whole selection with `model_names`, atomically:
+        # callers always submit the complete set they intend to keep, so
+        # deselecting a model is simply selecting a smaller set, and a
+        # partially written file can never be observed.
+        def replace(model_names)
+          normalized = normalize(model_names)
+          write(normalized)
+          Record.new(model_names: normalized, error: nil)
+        rescue StandardError => e
+          Record.new(model_names: normalized || [].freeze,
+                     error: "selection could not be saved (#{e.class})")
+        end
+
+        private
+
+        def root
+          return Rails.root.to_s if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+          Dir.pwd
+        end
+
+        # Rejects the whole document the moment any one entry is unusable,
+        # rather than silently dropping just that entry -- a hand-edited
+        # file that mostly looks right is exactly the case fail-closed
+        # exists for.
+        def rejection(document)
+          return "is not a Karst selection document" unless document.is_a?(Hash)
+          return "was written by an incompatible Karst version" unless document["version"] == SCHEMA_VERSION
+
+          selected = document["selected"]
+          return "is not a Karst selection document" unless selected.is_a?(Array)
+
+          "holds more than #{MAX_ENTRIES} entries" if selected.size > MAX_ENTRIES
+        end
+
+        def parse(document)
+          reason = rejection(document)
+          return failed(reason) if reason
+
+          raw = document["selected"]
+          unless raw.all? { |name| name.is_a?(String) && MODEL_NAME.match?(name) }
+            return failed("holds an entry Karst does not recognize")
+          end
+
+          Record.new(model_names: sort(raw.uniq).freeze, error: nil)
+        end
+
+        def normalize(model_names)
+          usable = model_names.map(&:to_s).grep(MODEL_NAME)
+          sort(usable.uniq).first(MAX_ENTRIES).freeze
+        end
+
+        def sort(names)
+          names.sort
+        end
+
+        def write(names)
+          target = path
+          FileUtils.mkdir_p(File.dirname(target))
+          temporary = "#{target}.#{Process.pid}.tmp"
+          File.write(temporary, "#{JSON.pretty_generate(document(names))}\n")
+          File.rename(temporary, target)
+        ensure
+          FileUtils.rm_f(temporary) if temporary
+        end
+
+        def document(names)
+          { "version" => SCHEMA_VERSION, "selected" => names }
+        end
+
+        def empty
+          Record.new(model_names: [].freeze, error: nil)
+        end
+
+        def failed(reason)
+          Record.new(model_names: [].freeze,
+                     error: "#{display_path} #{reason}; Karst selected no principal sources from it. " \
+                            "Delete the file and select again.")
+        end
+      end
+    end
+  end
+end