karst 0.1.0

data/lib/karst/access/selected_principal_sources.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "principal_source"
+require_relative "principal_source_selection"
+require_relative "approved_populations"
+require_relative "../identity/devise_support"
+
+module Karst
+  module Access
+    # Turns a locally selected set of ambiguous Devise models (see
+    # Karst::Access::PrincipalSourceSelection) into ordinary
+    # Karst::Access::PrincipalSource objects, one per selected model, each
+    # keyed by that model's own Devise/Warden scope -- so selecting both
+    # User and Admin produces two independently queryable sources
+    # (:user => ..., :admin => ...) exactly like a hand-written
+    # config.principal_sources would, never collapsed into one combined
+    # source.
+    #
+    # Every selected name is revalidated against
+    # Karst::Identity::DeviseSupport's *current* Devise.mappings on every
+    # call: a name the file stores but Devise no longer maps (removed,
+    # renamed) is silently dropped here, never constantized, and never
+    # trusted on the strength of the file alone. If that drops every
+    # selection, Karst is ambiguous again -- the developer is asked to
+    # select once more, exactly like the first time.
+    module SelectedPrincipalSources
+      class << self
+        # A Hash of Symbol(Devise scope) => PrincipalSource for every
+        # currently valid selected mapping, or nil when local selection does
+        # not apply at all (production, nothing selected, or every selected
+        # mapping is now stale).
+        def sources
+          valid = mappings
+          return nil if valid.empty?
+
+          valid.to_h do |mapping|
+            [mapping.scope, PrincipalSource.new(name: mapping.scope, records: -> { mapping.model.all })]
+          end
+        end
+
+        # The subset of Karst::Identity::DeviseSupport.mappings a developer
+        # has locally selected and that Devise still confirms right now --
+        # used both to build #sources above and by Karst::Identity's own
+        # ambiguous/ready checks, so neither has to know the storage format.
+        # Always [] outside development/test (see
+        # Karst::Access::ApprovedPopulations.local_environment?, the same
+        # local-preference gate approved populations already use) and on any
+        # failure -- selection is an optional convenience layered over
+        # Devise's own metadata, never something whose breakage should take
+        # down the panel, CLI, or MCP tool.
+        def mappings
+          return [] unless ApprovedPopulations.local_environment?
+
+          record = PrincipalSourceSelection.load
+          return [] if record.model_names.empty?
+
+          current = Identity::DeviseSupport.mappings
+          record.model_names.filter_map { |name| current.find { |mapping| mapping.model.name == name } }
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/karst/access/sensitive_attribute_names.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Karst
+  module Access
+    # Shared, deliberately conservative name-based PII filter used everywhere
+    # Karst decides whether an attribute name is safe to inspect or display --
+    # schema-derived sampling states (PrincipalSampler) above all.
+    # Column/attribute names are
+    # never PII-inspected, only compared (case-insensitive, underscore-
+    # tokenized) against this list. False positives (skipping a safe name)
+    # are free; false negatives are not, so this stays a single source of
+    # truth rather than being duplicated per caller.
+    module SensitiveAttributeNames
+      TOKENS = %w[
+        email name first last full phone mobile fax address street city zip
+        postal country ssn social security password secret salt encrypted
+        token key api credential auth login username url website dob birth
+        card cvv iban passport license
+      ].freeze
+
+      def self.match?(name)
+        name.to_s.downcase.split("_").any? { |token| TOKENS.include?(token) }
+      end
+    end
+  end
+end

data/lib/karst/access/sweep.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require "uri"
+require_relative "probe_application"
+require_relative "database_isolation"
+require_relative "../identity"
+require_relative "../value"
+
+module Karst
+  module Access
+    class Error < StandardError; end
+    class UnsafeTarget < Error; end
+    class UnsupportedMethod < Error; end
+    class Unavailable < Error; end
+
+    # sampling_reasons is a frozen Array of short evidence strings (e.g.
+    # "role=local_admin", "source=authors") explaining why PrincipalSampler
+    # or PrincipalSelection deliberately included this principal, or an
+    # empty Array when the principal came from plain first-N/fill sampling
+    # or was supplied directly rather than through a sampler. This is
+    # sampling evidence, not an authorization claim.
+    Outcome = Value.define(:principal, :status, :redirect, :exception_class,
+                           :writes_observed, :write_count, :elapsed_ms, :database_rollback_attempted,
+                           :sampling_reasons, :body_marker_observed, :halted_callback)
+
+    # candidate_pool_size is nil unless the caller supplying `principals` (see
+    # Access::PrincipalSampler::Result) knows it sampled from a bounded
+    # recent-N pool rather than the full principal source -- callers use it
+    # to report the sampling scope truthfully rather than implying every
+    # principal was considered.
+    Result = Value.define(:path, :http_method, :outcomes, :elapsed_ms, :aborted_reason, :database_isolation,
+                          :candidate_pool_size) do
+      def groups
+        outcomes.group_by { |item| [item.status, item.redirect, item.exception_class, item.halted_callback] }
+      end
+    end
+
+    # Sequentially observes one concrete local GET using a fresh integration
+    # session and a rollback-only transaction for every bounded principal.
+    # rubocop:disable Metrics/ClassLength
+    class Sweep
+      # sampling_reasons optionally maps a principal (by Ruby equality, so
+      # the same Active Record identity even across separate instances) to
+      # the Array of reasons it was selected for -- see
+      # Access::PrincipalSampler::Candidate/PrincipalSelection. A principal
+      # with no entry simply gets an empty Array on its Outcome.
+      # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Metrics/MethodLength
+      def initialize(path:, principals:, http_method: "GET", limit: Karst.config.access_sweep_limit,
+                     application: nil, candidate_pool_size: nil, sampling_reasons: {}, body_includes: nil)
+        @path = normalize_path(path)
+        @http_method = http_method.to_s.upcase
+        raise UnsupportedMethod, "access sweeps support GET only" unless @http_method == "GET"
+        raise ArgumentError, "limit exceeds configured access_sweep_limit" unless valid_limit?(limit)
+
+        @principals = principals
+        @limit = limit
+        @application = application || Rails.application
+        @probe_application = build_probe_application
+        @candidate_pool_size = candidate_pool_size
+        @sampling_reasons = sampling_reasons
+        @body_includes = body_includes
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/ParameterLists
+
+      def call
+        raise Unavailable, "access sweeps are development-only" unless Rails.env.development?
+        raise Unavailable, "Karst is disabled (config.enabled)" unless Karst.enabled?
+
+        require "action_dispatch/testing/integration" unless defined?(ActionDispatch::Integration::Session)
+
+        started = monotonic
+        outcomes = bounded_principals.map { |principal| probe(principal) }
+        Result.new(path: @path, http_method: @http_method, outcomes: outcomes.freeze,
+                   elapsed_ms: elapsed(started), aborted_reason: nil,
+                   database_isolation: :same_connection_rollback_attempted,
+                   candidate_pool_size: @candidate_pool_size)
+      end
+
+      private
+
+      def normalize_path(value)
+        raw = value.to_s.split("?", 2).first
+        uri = URI.parse(raw)
+        local = uri.relative? && raw.start_with?("/") && !raw.start_with?("//")
+        raise UnsafeTarget, "target must be a local application path" unless local
+
+        raw
+      rescue URI::InvalidURIError
+        raise UnsafeTarget, "target must be a valid local application path"
+      end
+
+      def valid_limit?(limit)
+        limit.is_a?(Integer) && limit.positive? && limit <= Karst.config.access_sweep_limit
+      end
+
+      def bounded_principals
+        source = @principals
+        source = source.limit(@limit) if source.respond_to?(:limit)
+        source.each.lazy.take(@limit).to_a
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def probe(principal)
+        session = ActionDispatch::Integration::Session.new(@probe_application)
+        configure_host(session)
+        started = monotonic
+        status = redirect = exception_class = nil
+        body_marker_observed = nil
+        halted_callback = nil
+        writes = 0
+        callback = lambda do |_name, _start, _finish, _id, payload|
+          writes += 1 if DatabaseIsolation.mutation?(payload[:sql])
+        end
+        halt_observer = lambda do |_name, _start, _finish, _id, payload|
+          halted_callback = payload[:filter]
+        end
+
+        with_rollback do
+          ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
+            Karst::Identity.with(session, principal) do
+              ActiveSupport::Notifications.subscribed(halt_observer, "halted_callback.action_controller") do
+                session.get(@path)
+              end
+              rendered_exception = request_exception(session)
+              if rendered_exception
+                exception_class = rendered_exception.class.name
+              else
+                status = session.response.status
+                if @body_includes && session.response.respond_to?(:body)
+                  body_marker_observed = session.response.body.to_s.include?(@body_includes.to_s)
+                end
+                redirect = clean_redirect(session.response.location) if status >= 300 && status < 400
+              end
+            end
+          end
+        rescue StandardError => e
+          exception_class = e.class.name
+        end
+        Outcome.new(principal: Karst::Identity.describe(principal), status: status, redirect: redirect,
+                    exception_class: exception_class, writes_observed: writes.positive?, write_count: writes,
+                    elapsed_ms: elapsed(started), database_rollback_attempted: true,
+                    sampling_reasons: (@sampling_reasons[principal] || []).freeze,
+                    body_marker_observed: body_marker_observed, halted_callback: halted_callback)
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      def with_rollback
+        raise Unavailable, "Active Record rollback isolation is unavailable" unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.transaction(requires_new: true) do
+          yield
+          raise ActiveRecord::Rollback
+        end
+      end
+
+      def build_probe_application
+        ProbeApplication.for(@application)
+      rescue ProbeApplication::ConstructionError => e
+        raise Unavailable, e.message, cause: e
+      end
+
+      def configure_host(session)
+        return unless @probe_application.respond_to?(:host) && @probe_application.host
+
+        session.host!(@probe_application.host)
+      end
+
+      # Rails may either re-raise an application exception or render it through
+      # ShowExceptions, depending on host and Rails-version configuration. The
+      # latter records the original exception in the integration request env.
+      def request_exception(session)
+        return unless session.respond_to?(:request) && session.request
+
+        session.request.get_header("action_dispatch.exception")
+      end
+
+      def clean_redirect(location)
+        return nil if location.to_s.empty?
+
+        URI.parse(location).tap { |uri| uri.query = nil }.to_s
+      rescue URI::InvalidURIError
+        location.to_s.split("?", 2).first
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def elapsed(started)
+        ((monotonic - started) * 1000.0).round(1)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/karst/cli/verification.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../karst"
+
+module Karst
+  module CLI
+    # Presentation-only adapter for Access::Search. It deliberately receives
+    # Search's result and converts only its public evidence values to stable,
+    # privacy-bounded primitives.
+    # Formatting necessarily enumerates the complete public schema in one
+    # place, keeping the versioned contract auditable.
+    # rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize
+    class Verification
+      SCHEMA_VERSION = 1
+
+      def initialize(path:, http_method: "GET", output: $stdout, json: false)
+        @path = path
+        @http_method = http_method
+        @output = output
+        @json = json
+      end
+
+      def call
+        result = run_search
+        @output.puts(@json ? JSON.generate(document(result)) : human(result))
+        result.verified_outcome ? 0 : 1
+      rescue Access::Error, Identity::Error, ArgumentError => e
+        @output.puts(@json ? JSON.generate(error_document(e)) : "Karst cannot verify this route:\n#{e.message}")
+        2
+      end
+
+      # The same schema-versioned evidence document --json prints, without
+      # any dependency on @output/stdout -- the shared entry point every
+      # other adapter (currently only the MCP server) calls instead of
+      # duplicating Access::Search invocation or result serialization. Always
+      # returns a Hash: either the success document or, on any of the same
+      # errors #call rescues, error_document(e) -- never raises.
+      def evidence
+        document(run_search)
+      rescue Access::Error, Identity::Error, ArgumentError => e
+        error_document(e)
+      end
+
+      private
+
+      def run_search
+        validate_setup!
+        Access::Search.new(path: @path, http_method: @http_method, sources: Identity.principal_sources).call
+      end
+
+      def validate_setup!
+        state = Identity.setup_state
+        return if state.status.to_s.start_with?("ready_")
+
+        message = state.message || "no principal source is configured"
+        raise Identity::ConfigurationError, message
+      end
+
+      def document(result)
+        winner = result.verified_outcome
+        {
+          schema_version: SCHEMA_VERSION,
+          request: { method: result.http_method, path: result.path },
+          verified_usable: !winner.nil?,
+          verified_principal: winner && principal(winner.principal),
+          verified_outcome: winner && outcome(winner, include_principal: false),
+          source: result.verified_source,
+          sample: sweep(result.initial),
+          populations: result.attempts.map { |attempt| population(attempt) },
+          summary: { request_count: result.request_count, elapsed_ms: result.elapsed_ms }
+        }
+      end
+
+      def sweep(result)
+        {
+          candidate_pool_size: result.candidate_pool_size,
+          users_tested: result.outcomes.size,
+          verified_usable: result.outcomes.any? { |item| Karst.config.usable_access_outcome.call(item) },
+          database_isolation: result.database_isolation.to_s,
+          outcomes: grouped_outcomes(result.outcomes)
+        }
+      end
+
+      def population(attempt)
+        data = { name: attempt.name.to_s, source: attempt.source_name.to_s, state: attempt.state.to_s }
+        data[:reason] = attempt.error if attempt.error
+        return data unless attempt.result
+
+        data.merge(users_tested: attempt.result.outcomes.size, outcomes: grouped_outcomes(attempt.result.outcomes))
+      end
+
+      def grouped_outcomes(outcomes)
+        outcomes.group_by { |item| outcome(item, include_principal: false) }.map do |evidence, items|
+          evidence.merge(count: items.size, principals: items.map { |item| principal(item.principal) })
+        end
+      end
+
+      def outcome(item, include_principal: true)
+        data = {
+          status: item.status, redirect: item.redirect, exception_class: item.exception_class,
+          halted_callback: item.halted_callback&.to_s, writes_observed: item.writes_observed,
+          write_count: item.write_count, database_rollback_attempted: item.database_rollback_attempted,
+          elapsed_ms: item.elapsed_ms
+        }
+        data[:principal] = principal(item.principal) if include_principal
+        data
+      end
+
+      def principal(value)
+        # JSON is also the MCP contract. Framework-inferred login identifiers
+        # must never cross that machine-readable boundary. An application-
+        # authored principal_label remains explicit configuration and keeps
+        # its longstanding serialization behavior.
+        label = if Karst.config.principal_label
+                  value.display_label.to_s
+                else
+                  "#{value.model_name} ##{value.id}"
+                end
+        { model: value.model_name.to_s, id: primitive_id(value.id), label: label }
+      end
+
+      def primitive_id(value)
+        value.is_a?(Integer) ? value : value.to_s
+      end
+
+      def error_document(error)
+        type = error.is_a?(Identity::Error) ? "configuration_error" : "input_error"
+        { schema_version: SCHEMA_VERSION, error: { type: type, message: error.message } }
+      end
+
+      def human(result)
+        lines = ["Karst verification", "", "#{result.http_method} #{result.path}", "", "Sample",
+                 "  #{result.initial.outcomes.size} users tested",
+                 "  #{sample_usable_count(result)} verified usable"]
+        append_key_evidence(lines, result.initial.outcomes)
+        append_populations(lines, result)
+        append_result(lines, result)
+        lines.join("\n")
+      end
+
+      def sample_usable_count(result)
+        result.initial.outcomes.count { |item| Karst.config.usable_access_outcome.call(item) }
+      end
+
+      def append_key_evidence(lines, outcomes)
+        evidence = outcomes.first
+        return unless evidence
+
+        lines << "  status #{evidence.status}" if evidence.status
+        lines << "  redirect #{evidence.redirect}" if evidence.redirect
+        lines << "  halted at #{evidence.halted_callback}" if evidence.halted_callback
+        lines << "  exception #{evidence.exception_class}" if evidence.exception_class
+        lines << "  WARNING: #{evidence.write_count} writes observed" if evidence.writes_observed
+      end
+
+      def append_populations(lines, result)
+        return if result.attempts.empty?
+
+        lines.push("", "Candidate populations")
+        result.attempts.each do |attempt|
+          count = attempt.result&.outcomes&.size || 0
+          lines << "  #{attempt.name}: #{attempt.state} (#{count} users tested)"
+          append_key_evidence(lines, attempt.result.outcomes) if attempt.result
+        end
+      end
+
+      def append_result(lines, result)
+        lines.push("", "Result")
+        if result.verified_outcome
+          lines << "  verified usable user: #{result.verified_outcome.principal.display_label}"
+          source = result.verified_source
+          lines << "  source: #{source[:type]}#{"=#{source[:name]}" if source[:name]}"
+        else
+          lines << "  no verified usable user found"
+        end
+        lines << "  #{result.request_count} requests in #{result.elapsed_ms} ms"
+      end
+    end
+    # rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize
+  end
+end