karst 0.1.0 → 0.4.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: karst
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Karst contributors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-12 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -34,16 +34,22 @@ dependencies:
   name: mcp
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
-  type: :runtime
+        version: 1.5.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '1.7'
 description: Karst tests Rails routes as a bounded set of existing users and reports
   runtime access evidence.
 email: 
@@ -59,6 +65,8 @@ files:
 - README.md
 - SECURITY.md
 - docs/advanced-configuration.md
+- docs/rails8-authentication.md
+- docs/request-reproduction.md
 - lib/generators/karst/install/install_generator.rb
 - lib/generators/karst/install/templates/karst_identity_controller.rb
 - lib/generators/karst/install/templates/karst_initializer.rb
@@ -66,40 +74,52 @@ files:
 - lib/karst/access/approved_populations.rb
 - lib/karst/access/candidate_population.rb
 - lib/karst/access/database_isolation.rb
+- lib/karst/access/errors.rb
+- lib/karst/access/identity_probe.rb
+- lib/karst/access/local_path.rb
+- lib/karst/access/observed_endpoint.rb
+- lib/karst/access/outcome_groups.rb
+- lib/karst/access/population_approval.rb
 - lib/karst/access/population_approvals.rb
-- lib/karst/access/population_config_snippet.rb
 - lib/karst/access/population_discovery.rb
-- lib/karst/access/population_preview.rb
+- lib/karst/access/population_revocation.rb
 - lib/karst/access/principal_sampler.rb
 - lib/karst/access/principal_selection.rb
 - lib/karst/access/principal_source.rb
 - lib/karst/access/principal_source_selection.rb
+- lib/karst/access/probe.rb
 - lib/karst/access/probe_application.rb
-- lib/karst/access/resource_evidence.rb
 - lib/karst/access/search.rb
 - lib/karst/access/selected_principal_sources.rb
 - lib/karst/access/sensitive_attribute_names.rb
 - lib/karst/access/sweep.rb
+- lib/karst/cli/identity_serialization.rb
+- lib/karst/cli/outcome_summary.rb
+- lib/karst/cli/principal_reference.rb
+- lib/karst/cli/reproduction.rb
 - lib/karst/cli/verification.rb
 - lib/karst/configuration.rb
 - lib/karst/execution_context.rb
 - lib/karst/identity.rb
 - lib/karst/identity/devise_support.rb
+- lib/karst/identity/evidence.rb
+- lib/karst/identity/observation.rb
 - lib/karst/identity/warden_adapter.rb
+- lib/karst/mcp/compatibility.rb
+- lib/karst/mcp/reproduce_request_tool.rb
+- lib/karst/mcp/reproduction.rb
 - lib/karst/mcp/server.rb
 - lib/karst/mcp/verify_access_tool.rb
 - lib/karst/railtie.rb
-- lib/karst/spec/catalog.rb
-- lib/karst/spec/example_observation.rb
-- lib/karst/spec/observer.rb
-- lib/karst/spec/principal.rb
-- lib/karst/spec/reporter.rb
-- lib/karst/spec/request_observation.rb
-- lib/karst/spec/scenario.rb
+- lib/karst/reproduction/curl.rb
+- lib/karst/reproduction/exercise.rb
+- lib/karst/reproduction/observation.rb
+- lib/karst/reproduction/sanitizer.rb
 - lib/karst/value.rb
 - lib/karst/version.rb
 - lib/karst/web/badge.rb
 - lib/karst/web/browser_identity.rb
+- lib/karst/web/csrf.rb
 - lib/karst/web/locality.rb
 - lib/karst/web/middleware.rb
 - lib/karst/web/panel.rb
@@ -107,8 +127,8 @@ files:
 - lib/karst/web/route_lookup.rb
 - lib/rails/commands/karst/boot.rb
 - lib/rails/commands/karst/mcp/mcp_command.rb
+- lib/rails/commands/karst/reproduce/reproduce_command.rb
 - lib/rails/commands/karst/verify/verify_command.rb
-- lib/tasks/karst.rake
 homepage: https://github.com/SilenceDogood1984/karst
 licenses:
 - MIT

data/lib/karst/access/population_config_snippet.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../value"
-
-module Karst
-  module Access
-    # Renders a developer's curated selection of
-    # Karst::Access::PopulationDiscovery::Candidate into a Ruby config
-    # snippet they can copy into their own Karst.configure block. Karst
-    # never writes to the host application's files on its own -- the
-    # developer stays in control of what actually gets committed (see
-    # README "Curation / persistence").
-    module PopulationConfigSnippet
-      # wired is the subset actually rendered into `code` (every selected
-      # candidate whose model matches a configured principal source).
-      # unwired is every selected candidate that is not wired into
-      # anything yet -- present so the UI can say so honestly instead of
-      # silently dropping a selection (see README "Principal vs artifact
-      # populations": this release only wires principal populations).
-      Result = Value.define(:code, :wired, :unwired)
-
-      class << self
-        def generate(candidates)
-          unique = candidates.uniq { |candidate| [candidate.model_name, candidate.method_name] }
-          wired, unwired = unique.partition(&:principal_source)
-          Result.new(code: render(wired), wired: wired, unwired: unwired)
-        end
-
-        private
-
-        def render(wired)
-          return "# Select at least one population above to generate a configuration snippet.\n" if wired.empty?
-
-          by_source = wired.group_by(&:principal_source)
-          by_source.size == 1 && by_source.keys.first == :default ? flat(by_source.fetch(:default)) : nested(by_source)
-        end
-
-        def flat(candidates)
-          "config.principal_populations = {\n#{entries(candidates, indent: 2)}\n}\n"
-        end
-
-        def nested(by_source)
-          sources = by_source.map do |source, group|
-            "  #{source_key(source)}: {\n    populations: {\n#{entries(group, indent: 6)}\n    }\n  }"
-          end.join(",\n")
-          "config.principal_sources = {\n#{sources}\n}\n"
-        end
-
-        # Sorted by model then method so the same selection always renders
-        # byte-identical output, regardless of checkbox submission order.
-        def entries(candidates, indent:)
-          pad = " " * indent
-          sorted = candidates.sort_by { |candidate| [candidate.model_name, candidate.method_name.to_s] }
-          sorted.map { |candidate| entry(candidate, pad) }.join(",\n")
-        end
-
-        def entry(candidate, pad)
-          "#{pad}#{candidate.method_name}: -> { #{candidate.model_name}.#{candidate.method_name} }"
-        end
-
-        def source_key(source)
-          source.to_s =~ /\A[a-zA-Z_][a-zA-Z0-9_]*\z/ ? source : source.inspect
-        end
-      end
-    end
-  end
-end

data/lib/karst/access/population_preview.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../value"
-require_relative "candidate_population"
-
-module Karst
-  module Access
-    # The explicit, bounded "does this discovered candidate actually work"
-    # step -- deliberately separate from Karst::Access::PopulationDiscovery,
-    # which never executes anything. Only ever resolves a model/method pair
-    # that a given Karst::Access::PopulationDiscovery::Result itself already
-    # discovered; a submitted name that is not on that list is rejected
-    # without calling anything, so this can never become a general "call any
-    # class method by name" endpoint. Every resolution is bounded to
-    # PREVIEW_LIMIT rows via Karst::Access::CandidatePopulation.resolve --
-    # never a COUNT, never full materialization.
-    class PopulationPreview
-      PREVIEW_LIMIT = 3
-
-      Result = Value.define(:model_name, :method_name, :resolved, :records, :error)
-
-      def self.call(model_name:, method_name:, discovery_result:)
-        new(model_name: model_name, method_name: method_name, discovery_result: discovery_result).call
-      end
-
-      def initialize(model_name:, method_name:, discovery_result:)
-        @model_name = model_name.to_s
-        @method_name = method_name.to_s
-        @discovery_result = discovery_result
-      end
-
-      def call
-        return unresolved("this is not a discovered candidate") unless known_candidate?
-
-        klass = model_class
-        return unresolved("the model could not be resolved") unless klass
-
-        resolve(klass)
-      end
-
-      private
-
-      def known_candidate?
-        @discovery_result.candidates.any? do |candidate|
-          candidate.model_name == @model_name && candidate.method_name.to_s == @method_name
-        end
-      end
-
-      def model_class
-        return nil unless defined?(ActiveRecord::Base)
-
-        ActiveRecord::Base.descendants.find { |klass| klass.name == @model_name }
-      end
-
-      def resolve(klass)
-        method_name = @method_name
-        return missing_scope unless scope_exists?(klass, method_name)
-
-        population = CandidatePopulation.resolve(
-          name: method_name.to_sym, callable: -> { klass.public_send(method_name) },
-          source_klass: klass, limit: PREVIEW_LIMIT
-        )
-        return unresolved("did not resolve to a usable ActiveRecord::Relation for #{@model_name}") unless population
-
-        Result.new(model_name: @model_name, method_name: @method_name, resolved: true, records: population.records,
-                   error: nil)
-      end
-
-      def scope_exists?(klass, method_name)
-        klass.respond_to?(method_name)
-      end
-
-      def missing_scope
-        unresolved("the discovered scope no longer exists on #{@model_name}")
-      end
-
-      def unresolved(error)
-        Result.new(model_name: @model_name, method_name: @method_name, resolved: false, records: [].freeze,
-                   error: error)
-      end
-    end
-  end
-end

data/lib/karst/access/resource_evidence.rb

@@ -1,233 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support/core_ext/string/inflections"
-require_relative "../value"
-require_relative "../identity"
-
-module Karst
-  module Access
-    # Given one exact resource (the specific record a route addresses by id)
-    # and one specific principal (typically the successful outcome from an
-    # Access::Sweep), reports simple, directly observed foreign-key
-    # relationships between those two records. This is evidence, not an
-    # authorization claim: it never states or implies *why* an outcome
-    # occurred, only which foreign-key columns, if any, point from one given
-    # record to the other's id.
-    #
-    # Deliberately narrow, matching the v1 scope this class was built for:
-    # - only foreign-key-shaped columns (ending in "_id") on the two given
-    #   records are ever inspected -- never an arbitrary attribute, so no
-    #   other column value (name, email, token, ...) is ever read or shown;
-    # - only a direct column-value comparison between the two given records,
-    #   never a join, a has_many traversal, or any multi-hop graph walk;
-    # - resource resolution from a route path is attempted only through
-    #   Rails' own route recognition plus its controller-to-model naming
-    #   convention, and only trusted when every step succeeds unambiguously
-    #   (a recognized route with an :id segment, a controller name that
-    #   classifies to a real loaded Active Record class, and a record that
-    #   actually exists for that id). Anything softer -- an unrecognized
-    #   route, a controller with no conventional model, a missing record --
-    #   is reported as a limitation rather than guessed at.
-    # rubocop:disable Metrics/ClassLength
-    class ResourceEvidence
-      class Error < StandardError; end
-
-      # The resource side never gets Identity::PrincipalDescriptor's
-      # configurable display_label hook -- there is no equivalent concept
-      # for "the current route's resource" -- so it gets its own minimal,
-      # equally attribute-free descriptor.
-      ResourceDescriptor = Value.define(:model_name, :id)
-
-      # from_model/from_id is whichever of the resource/principal actually
-      # holds the foreign-key column; to_model/to_id is the other side.
-      Relationship = Value.define(:column, :from_model, :from_id, :to_model, :to_id)
-
-      Result = Value.define(:principal, :resource, :relationships, :observed_status, :observed_redirect,
-                            :limitation) do
-        # Plain-text rendering deliberately kept free of causal wording
-        # ("owns", "is authorized", "grants") -- see class comment above.
-        def to_text
-          lines = [principal.display_label]
-          lines << observed_line if observed_status || observed_redirect
-          lines << "" << "Related state:"
-          lines.concat(related_state_lines)
-          lines.join("\n")
-        end
-
-        private
-
-        def observed_line
-          observed_redirect ? "Observed #{observed_status} → #{observed_redirect}" : "Observed #{observed_status}"
-        end
-
-        def related_state_lines
-          return ["  Unavailable: #{limitation}"] if limitation
-          return [no_relationship_line] if relationships.empty?
-
-          grouped_relationship_lines
-        end
-
-        def no_relationship_line
-          "  No observed foreign-key relationship to #{resource.model_name} ##{resource.id}."
-        end
-
-        def grouped_relationship_lines
-          relationships.group_by { |rel| [rel.from_model, rel.from_id] }.flat_map do |(model, id), grouped|
-            ["#{model} ##{id}"] + grouped.map { |rel| "  #{rel.column} → #{rel.to_model} ##{rel.to_id}" }
-          end
-        end
-      end
-
-      class << self
-        # Resolves the resource, resolves the principal (from a
-        # Sweep::Outcome's PrincipalDescriptor), and reports relationships in
-        # one call. Either resolution step may fail safely -- see
-        # #resolve_resource and #resolve_principal -- in which case the
-        # Result carries a limitation instead of relationships.
-        def for_outcome(outcome:, path:, http_method: "GET", application: nil)
-          resource, resource_limitation = resolve_resource(path: path, http_method: http_method,
-                                                           application: application)
-          principal, principal_limitation = resolve_principal(outcome.principal)
-          limitation = [resource_limitation, principal_limitation].compact.join("; ")
-
-          return unresolved_result(outcome, limitation) if resource.nil? || principal.nil?
-
-          new(resource: resource, principal: principal).call(
-            observed_status: outcome.status, observed_redirect: outcome.redirect
-          )
-        end
-
-        # Attempts to resolve the exact record a route addresses, trusting
-        # only Rails' own route recognition and controller naming
-        # convention, and only when every step is unambiguous. Returns
-        # [record, nil] on success or [nil, reason] when any step is not
-        # reliable -- never a guessed record.
-        def resolve_resource(path:, http_method: "GET", application: nil)
-          app = application || rails_application
-          return [nil, "no Rails application is available to recognize the route"] unless app
-
-          params = recognize(app, path, http_method)
-          return [nil, "the route could not be recognized"] unless params
-
-          id = params[:id]
-          return [nil, "the recognized route has no :id segment addressing one specific resource"] unless id
-
-          find_by_controller(params[:controller], id)
-        end
-
-        # Resolves the actual record behind a Karst::Identity::PrincipalDescriptor
-        # only through the configured principal source. A valid model/id outside
-        # that source is deliberately unresolved.
-        def resolve_principal(descriptor)
-          record = Identity.resolve(model_name: descriptor.model_name, id: descriptor.id)
-          return [nil, "principal is not available from the configured principal source"] unless record
-
-          [record, nil]
-        rescue Identity::Error
-          [nil, "the configured principal source is unavailable"]
-        end
-
-        private
-
-        def rails_application
-          defined?(Rails) && Rails.respond_to?(:application) && Rails.application
-        end
-
-        def find_by_controller(controller, id)
-          klass = active_record_class(controller.to_s.classify)
-          return [nil, "the route's controller does not map to a loaded Active Record model by convention"] unless klass
-
-          record = klass.find_by(klass.primary_key => id)
-          return [nil, "no #{klass.name} record exists for id #{id.inspect}"] unless record
-
-          [record, nil]
-        end
-
-        def unresolved_result(outcome, limitation)
-          Result.new(principal: outcome.principal, resource: nil, relationships: [].freeze,
-                     observed_status: outcome.status, observed_redirect: outcome.redirect,
-                     limitation: limitation.empty? ? "the resource or principal could not be resolved" : limitation)
-        end
-
-        def recognize(app, path, http_method)
-          app.routes.recognize_path(path, method: http_method)
-        rescue StandardError
-          nil
-        end
-
-        def active_record_class(name)
-          klass = name.to_s.safe_constantize
-          return nil unless defined?(ActiveRecord::Base) && klass.is_a?(Class) && klass < ActiveRecord::Base
-
-          klass
-        end
-      end
-
-      def initialize(resource:, principal:)
-        @resource = resource
-        @principal = principal
-      end
-
-      def call(observed_status: nil, observed_redirect: nil)
-        Result.new(
-          principal: Identity.describe(@principal),
-          resource: ResourceDescriptor.new(model_name: model_name(@resource), id: primary_key_value(@resource)),
-          relationships: relationships.freeze,
-          observed_status: observed_status,
-          observed_redirect: observed_redirect,
-          limitation: nil
-        )
-      end
-
-      private
-
-      def relationships
-        foreign_keys_from(@resource, @principal) + foreign_keys_from(@principal, @resource)
-      end
-
-      def foreign_keys_from(source, target)
-        return [] unless active_record?(source) && active_record?(target)
-
-        source.class.columns_hash.values.filter_map { |column| relationship_for(source, target, column) }
-      end
-
-      def relationship_for(source, target, column)
-        return unless foreign_key_column?(source.class, column)
-        return unless targets?(column, target.class)
-
-        value = source.public_send(column.name)
-        return if value.nil? || value != primary_key_value(target)
-
-        Relationship.new(column: column.name, from_model: model_name(source), from_id: primary_key_value(source),
-                         to_model: model_name(target), to_id: primary_key_value(target))
-      end
-
-      def foreign_key_column?(klass, column)
-        column.name.end_with?("_id") && column.name != klass.primary_key
-      end
-
-      # "Obvious" is judged purely from the column's own name against the
-      # target's actual class (including its Active Record ancestry, so a
-      # single-table-inherited subclass still matches its base class's
-      # conventional foreign key) -- never a declared association, never any
-      # other column's value, and never a second hop through another model.
-      def targets?(column, target_klass)
-        candidate = column.name.delete_suffix("_id").classify.safe_constantize
-        candidate.is_a?(Class) && (target_klass <= candidate || candidate <= target_klass)
-      end
-
-      def active_record?(record)
-        defined?(ActiveRecord::Base) && record.is_a?(ActiveRecord::Base)
-      end
-
-      def model_name(record)
-        record.class.respond_to?(:model_name) ? record.class.model_name.name.to_s : record.class.name.to_s
-      end
-
-      def primary_key_value(record)
-        record.public_send(record.class.primary_key)
-      end
-    end
-    # rubocop:enable Metrics/ClassLength
-  end
-end