karst 0.1.0 → 0.2.0

data/lib/karst/access/population_approval.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "population_approvals"
+
+module Karst
+  module Access
+    # Adds explicitly selected candidates from one current discovery pass to
+    # the local approval record. Submitted values are treated only as keys:
+    # the Entry objects written below always come from discovery itself.
+    class PopulationApproval
+      Result = Value.define(:record, :error) do
+        def saved?
+          error.nil? && record.error.nil?
+        end
+      end
+
+      SEPARATOR = "::"
+
+      def initialize(discovery:, principal_sources:, submitted:, record: PopulationApprovals.load)
+        @discovery = discovery
+        @principal_sources = principal_sources
+        @submitted = Array(submitted).map(&:to_s)
+        @record = record
+      end
+
+      def call
+        selected = selected_candidates
+        return rejected("Select at least one current candidate population.") if @submitted.empty?
+        return rejected("A submitted population is no longer available for this principal source.") unless selected
+
+        entries = @record.entries + selected.map do |candidate|
+          PopulationApprovals::Entry.new(model_name: candidate.model_name,
+                                         method_name: candidate.method_name.to_s)
+        end
+        record = PopulationApprovals.replace(entries)
+        Result.new(record: record, error: record.error)
+      end
+
+      private
+
+      def selected_candidates
+        candidates = applicable_candidates
+        by_key = candidates.to_h { |candidate| [candidate_key(candidate), candidate] }
+        return unless @submitted.uniq.size == @submitted.size
+        return unless @submitted.all? { |key| by_key.key?(key) }
+
+        @submitted.map { |key| by_key.fetch(key) }
+      end
+
+      def applicable_candidates
+        names = @principal_sources.keys.map(&:to_s)
+        @discovery.candidates.select do |candidate|
+          candidate.principal_source && names.include?(candidate.principal_source.to_s) &&
+            !@record.approved?(candidate.model_name, candidate.method_name)
+        end
+      end
+
+      def candidate_key(candidate)
+        [candidate.principal_source, candidate.model_name, candidate.method_name].join(SEPARATOR)
+      end
+
+      def rejected(message)
+        Result.new(record: @record, error: message)
+      end
+    end
+  end
+end

data/lib/karst/access/population_revocation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "population_approvals"
+
+module Karst
+  module Access
+    # Removes one exact, already-stored approval while preserving every other
+    # entry. Submitted values can never add or alter an approval.
+    class PopulationRevocation
+      Result = Value.define(:record, :revoked)
+
+      SEPARATOR = "::"
+
+      def initialize(submitted:, record: PopulationApprovals.load)
+        @submitted = submitted.to_s
+        @record = record
+      end
+
+      def call
+        entry = @record.entries.find { |candidate| key(candidate) == @submitted }
+        return Result.new(record: @record, revoked: false) unless entry
+
+        record = PopulationApprovals.replace(@record.entries - [entry])
+        Result.new(record: record, revoked: record.error.nil?)
+      end
+
+      private
+
+      def key(entry)
+        [entry.model_name, entry.method_name].join(SEPARATOR)
+      end
+    end
+  end
+end

data/lib/karst/configuration.rb

@@ -15,8 +15,8 @@ module Karst
   # 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
+  # inferred outright, candidate populations are approved inline at /karst
+  # 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
@@ -83,7 +83,7 @@ module Karst
                    "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",
+                            "populations approved after a failed /karst analysis",
       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
@@ -110,8 +110,8 @@ module Karst
     #     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
+    # This is the committed-to-source form of what /karst 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

data/lib/karst/execution_context.rb

@@ -9,11 +9,10 @@ rescue LoadError
 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
+  # Request-local correlation storage used by the page badge to carry evidence
+  # from a notification callback fired inside a Rack call back out to the code that
   # reads it, without a global mutable variable that would let concurrent
-  # requests or examples cross-contaminate each other.
+  # requests cross-contaminate each other.
   #
   # Modern Rails already solves exactly this with
   # ActiveSupport::IsolatedExecutionState, so Karst simply delegates to it
@@ -23,9 +22,9 @@ module Karst
   # 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
+  # thread, not isolated per Fiber. Karst's own usage (one badge correlation
+  # captured and read back within a single synchronous request) 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.

data/lib/karst/railtie.rb

@@ -3,9 +3,10 @@
 require "rails/railtie"
 
 module Karst
-  # Inserts Karst's development-only web surface and rake tasks. Karst
-  # installs no notification subscription, no eager-loaded state, and nothing
-  # that runs on an ordinary application request outside development.
+  # Inserts Karst's development-only web surface. Karst installs no
+  # notification subscription, no eager-loaded state, no rake tasks (its CLI
+  # ships as Rails::Command classes under lib/rails/commands instead), and
+  # nothing that runs on an ordinary application request outside development.
   class Railtie < Rails::Railtie
     # Must run before the middleware stack is built (a later Finisher
     # initializer), not in config.after_initialize, which runs after the stack
@@ -20,10 +21,6 @@ module Karst
 
       Rails.logger&.info("Karst: evidence at /karst")
     end
-
-    rake_tasks do
-      load File.expand_path("../tasks/karst.rake", __dir__)
-    end
   end
 
   private_constant :Railtie

data/lib/karst/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Karst
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/karst/web/badge.rb

@@ -3,20 +3,13 @@
 require "cgi"
 require "rack/utils"
 
-begin
-  require_relative "../spec/catalog"
-rescue LoadError
-  # Degrades to a countless badge rather than preventing the host response
-  # from being served, mirroring Panel's own posture toward a missing Catalog.
-end
-
 module Karst
   module Web
     # Rewrites an eligible host HTML response to add a small, page-local link
-    # into Karst's route-scoped scenario catalog. Every check here exists to
-    # make injection safe to skip: Badge never guesses, never raises into the
-    # host application, and never touches a response it cannot confidently
-    # rewrite -- an untouched response is always the safe fallback.
+    # to Karst's route access panel. Every check here exists to make injection
+    # safe to skip: Badge never guesses, never raises into the host application,
+    # and never touches a response it cannot confidently rewrite -- an untouched
+    # response is always the safe fallback.
     #
     # Route identity (controller/action/http_method) comes from
     # Middleware, itself derived from a real process_action.action_controller
@@ -109,9 +102,8 @@ module Karst
 
         def markup(headers:, context:)
           href = escape("/karst?#{query_for(context)}")
-          label = escape(label_for(context))
           style = inline_style_allowed?(headers) ? " style=\"#{BADGE_STYLE}\"" : ""
-          "<a href=\"#{href}\"#{style}>#{label}</a>"
+          "<a href=\"#{href}\"#{style}>Karst</a>"
         end
 
         def query_for(context)
@@ -121,24 +113,6 @@ module Karst
           )
         end
 
-        def label_for(context)
-          catalog = load_catalog
-          return "Karst" unless catalog && catalog.status == :ready
-
-          count = catalog.scenarios_for(
-            controller: context.controller, action: context.action, http_method: context.http_method
-          ).size
-          "Karst · #{count}"
-        end
-
-        def load_catalog
-          return nil unless defined?(Karst::Spec::Catalog)
-
-          Karst::Spec::Catalog.load
-        rescue StandardError
-          nil
-        end
-
         # A CSP the host response itself declares is the only signal Badge
         # trusts: Karst never rewrites that header, only reads it, and falls
         # back to an unstyled link rather than risk a silently-dropped style

data/lib/karst/web/browser_identity.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
-require "securerandom"
 require "uri"
-require "active_support/security_utils"
+require_relative "csrf"
 
 module Karst
   module Web
-    # State-changing browser identity operations and their same-session CSRF
-    # token. Rails controller CSRF is unavailable because /karst is served at
-    # the Rack boundary, before Action Controller dispatch.
+    # State-changing browser identity operations. Synchronizer-token behavior
+    # belongs to Web::Csrf and is shared with other Rack-boundary forms.
     class BrowserIdentity
-      TOKEN_KEY = "karst.csrf_token"
       ACTIVE_KEY = "karst.browser_identity_active"
 
       # The exact Devise/Warden scope the currently assumed identity was
@@ -20,12 +17,13 @@ module Karst
       # several selected sources produced the principal being cleared.
       SCOPE_KEY = "karst.browser_identity_scope"
 
-      def initialize(request)
+      def initialize(request, csrf: Csrf.new(request))
         @request = request
+        @csrf = csrf
       end
 
       def token
-        session[TOKEN_KEY] ||= SecureRandom.hex(32)
+        @csrf.token
       end
 
       def active?
@@ -68,14 +66,13 @@ module Karst
       end
 
       def verify_token!(submitted)
-        expected = session[TOKEN_KEY]
-        valid = expected && submitted && expected.bytesize == submitted.bytesize &&
-                ActiveSupport::SecurityUtils.secure_compare(expected, submitted)
-        raise Identity::Unavailable, "invalid Karst CSRF token" unless valid
+        @csrf.verify!(submitted)
+      rescue Csrf::InvalidToken => e
+        raise Identity::Unavailable, e.message
       end
 
       def rotate_token!
-        session[TOKEN_KEY] = SecureRandom.hex(32)
+        @csrf.rotate!
       end
 
       # A blank path is not a caller error: the panel renders this same

data/lib/karst/web/csrf.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "active_support/security_utils"
+
+module Karst
+  module Web
+    # Synchronizer-token protection for state-changing forms served directly
+    # from Karst's Rack middleware, where Action Controller CSRF is unavailable.
+    class Csrf
+      TOKEN_KEY = "karst.csrf_token"
+
+      class InvalidToken < StandardError; end
+
+      def initialize(request)
+        @request = request
+      end
+
+      def token
+        session[TOKEN_KEY] ||= SecureRandom.hex(32)
+      end
+
+      def verify!(submitted)
+        expected = session[TOKEN_KEY]
+        valid = expected && submitted && expected.bytesize == submitted.bytesize &&
+                ActiveSupport::SecurityUtils.secure_compare(expected, submitted)
+        raise InvalidToken, "invalid Karst CSRF token" unless valid
+      end
+
+      def rotate!
+        session[TOKEN_KEY] = SecureRandom.hex(32)
+      end
+
+      private
+
+      def session
+        @request.session
+      rescue StandardError
+        raise InvalidToken, "a writable Rack session is required"
+      end
+    end
+  end
+end

data/lib/karst/web/middleware.rb

@@ -5,6 +5,7 @@ require_relative "panel"
 require_relative "populations_panel"
 require_relative "badge"
 require_relative "browser_identity"
+require_relative "csrf"
 require_relative "route_lookup"
 require_relative "../execution_context"
 require "rack/utils"
@@ -18,9 +19,9 @@ require_relative "../access/candidate_population"
 require_relative "../access/population_discovery"
 require_relative "../access/population_approvals"
 require_relative "../access/approved_populations"
-require_relative "../access/population_preview"
-require_relative "../access/population_config_snippet"
 require_relative "../access/principal_source_selection"
+require_relative "../access/population_approval"
+require_relative "../access/population_revocation"
 require_relative "../identity/devise_support"
 
 module Karst
@@ -52,9 +53,6 @@ module Karst
       POPULATIONS_PATH = "/karst/populations"
       private_constant :POPULATIONS_PATH
 
-      CANDIDATE_SEPARATOR = "::"
-      private_constant :CANDIDATE_SEPARATOR
-
       CONTEXT_KEY = :karst_web_request_context
       private_constant :CONTEXT_KEY
 
@@ -85,15 +83,21 @@ module Karst
         selection, denied = principal_source_selection_result(env, params)
         return denied if denied
 
-        browser_identity = BrowserIdentity.new(Rack::Request.new(env))
+        request = Rack::Request.new(env)
+        csrf = Csrf.new(request)
+        browser_identity = BrowserIdentity.new(request, csrf: csrf)
+        approval, denied = inline_population_approval_result(env, params, csrf)
+        return denied if denied
+
         identity_response = mutate_browser_identity(env, params, browser_identity)
         return identity_response if identity_response
 
-        result = analyze(env, params)
+        result = analyze(env, params, approval: approval)
+        candidates = inline_population_candidates(result)
         Panel.render(params: params, access_result: result, route_lookup_limitation: lookup&.limitation,
-                     csrf_token: browser_token(browser_identity),
+                     csrf_token: csrf_token(csrf),
                      browser_identity_active: browser_identity_active?(browser_identity),
-                     unapproved_candidate_count: unapproved_candidate_count(result),
+                     unapproved_candidates: candidates, population_approval_error: approval&.error,
                      principal_source_selection_saved: !selection.nil? && selection.error.nil?,
                      principal_source_selection_error: selection&.error)
       end
@@ -119,6 +123,19 @@ module Karst
         env["REQUEST_METHOD"] == "POST" && params["operation"] == "select_principal_sources"
       end
 
+      def inline_population_approval_result(env, params, csrf)
+        return [nil, nil] unless env["REQUEST_METHOD"] == "POST" && params["operation"] == "approve_populations"
+        return [nil, forbidden] unless approved_origin?(env)
+
+        csrf.verify!(params["csrf_token"])
+        discovery = Access::PopulationDiscovery.new.call
+        approval = Access::PopulationApproval.new(discovery: discovery, principal_sources: Identity.principal_sources,
+                                                  submitted: params["population"]).call
+        [approval, nil]
+      rescue Csrf::InvalidToken, Identity::Error
+        [nil, forbidden]
+      end
+
       # Only a model Devise itself currently maps can ever be written --
       # exactly like candidate-population approval only ever writes a
       # currently discovered scope -- so this form can never seed the file
@@ -130,58 +147,30 @@ module Karst
         Access::PrincipalSourceSelection.replace(names)
       end
 
-      # Unlike every other operation Karst serves, approving writes local
-      # state that outlives the request, so every POST to this path must
+      # Revocation changes local state that outlives the request, so every
+      # POST to this path must
       # have come from Karst's own page. There is no Rack session to hang a
       # CSRF token on here (this page deliberately touches none), so the
       # check is same-origin rather than token-based; a cross-site form POST
-      # cannot forge Origin, so it cannot approve anything. GET -- the page
+      # cannot forge Origin, so it cannot revoke anything. GET -- the page
       # itself -- stays unauthenticated exactly like /karst.
       def call_populations(env)
         return forbidden unless approved_origin?(env)
 
         params = owned_params(env)
-        discovery = Access::PopulationDiscovery.new.call
-        saving = saving_approvals?(env, params)
-        record = saving ? save_approvals(discovery, params) : Access::PopulationApprovals.load
-        render_populations(discovery, params, record, saving)
+        revoking = env["REQUEST_METHOD"] == "POST" && params["operation"] == "revoke_population"
+        result = Access::PopulationRevocation.new(submitted: params["population"]).call if revoking
+        record = result&.record || Access::PopulationApprovals.load
+        render_populations(record, result&.revoked)
       end
 
-      def render_populations(discovery, params, record, saved)
-        approved = approved_candidates(discovery, record)
-        snippet = Access::PopulationConfigSnippet.generate(approved) if params["generate_snippet"]
+      def render_populations(record, revoked)
         Web::PopulationsPanel.render(
-          discovery: discovery, approved: record.entries, stale: stale_approvals(record),
-          snippet: snippet, preview: population_preview(discovery, params),
-          storage_path: Access::PopulationApprovals.display_path, storage_error: record.error, saved: saved
+          approved: record.entries, stale: stale_approvals(record),
+          storage_path: Access::PopulationApprovals.display_path, storage_error: record.error, revoked: revoked
         )
       end
 
-      def saving_approvals?(env, params)
-        env["REQUEST_METHOD"] == "POST" && params.key?("save_approvals")
-      end
-
-      # Only a candidate the *current* discovery result actually lists can
-      # ever be written, so the file cannot be seeded through this form with
-      # a model/scope pair Karst would refuse to confirm later anyway.
-      def save_approvals(discovery, params)
-        raw = Array(params["population"]).map(&:to_s)
-        entries = discovery.candidates.filter_map do |candidate|
-          next unless raw.include?(candidate_key(candidate))
-
-          Access::PopulationApprovals::Entry.new(model_name: candidate.model_name,
-                                                 method_name: candidate.method_name.to_s)
-        end
-        Access::PopulationApprovals.replace(entries)
-      end
-
-      # Discovery candidates (which carry principal-source metadata the
-      # snippet generator needs) for the approved entries that are still
-      # discovered at all.
-      def approved_candidates(discovery, record)
-        discovery.candidates.select { |candidate| record.approved?(candidate.model_name, candidate.method_name) }
-      end
-
       def stale_approvals(record)
         Access::ApprovedPopulations.stale(safe_principal_sources, record: record)
       rescue StandardError
@@ -213,21 +202,6 @@ module Karst
         [403, { "content-type" => "text/plain; charset=utf-8", "cache-control" => "no-store" }, ["Forbidden"]]
       end
 
-      def population_preview(discovery, params)
-        key = params["preview"].to_s
-        return nil if key.empty?
-
-        candidate = discovery.candidates.find { |item| candidate_key(item) == key }
-        return nil unless candidate
-
-        Access::PopulationPreview.call(model_name: candidate.model_name, method_name: candidate.method_name,
-                                       discovery_result: discovery)
-      end
-
-      def candidate_key(candidate)
-        "#{candidate.model_name}#{CANDIDATE_SEPARATOR}#{candidate.method_name}"
-      end
-
       def call_with_badge(env)
         Karst::ExecutionContext[CONTEXT_KEY] = nil
         status, headers, body = @app.call(env)
@@ -262,9 +236,9 @@ module Karst
       # "try this population" operation for a developer to press --
       # and no path by which a merely discovered, unapproved population
       # name can be executed.
-      def analyze(env, params)
+      def analyze(env, params, approval: nil)
         return nil unless env["REQUEST_METHOD"] == "POST"
-        return nil unless params["operation"] == "access_sweep"
+        return nil unless params["operation"] == "access_sweep" || approval
 
         Access::Search.new(path: params["path"], http_method: params["method"],
                            sources: Identity.principal_sources).call
@@ -272,22 +246,21 @@ module Karst
         e
       end
 
-      # How many application-defined groups on an already-configured user
-      # source a developer could still approve. Computed only after an
+      # Application-defined groups on an already-configured user source a
+      # developer could still approve. Computed only after an
       # analysis that found nothing usable -- the one moment the answer is
       # actionable -- so an ordinary panel render never parses model source,
-      # and the main page never turns into a population-configuration
-      # workflow. Discovery executes nothing; see PopulationDiscovery.
-      def unapproved_candidate_count(result)
-        return nil unless result.is_a?(Access::Search::Result) && result.verified_outcome.nil?
+      # and the main page stays a contextual approval step rather than a
+      # population-management dashboard. Discovery executes nothing.
+      def inline_population_candidates(result)
+        return [] unless result.is_a?(Access::Search::Result) && result.verified_outcome.nil?
 
         record = Access::PopulationApprovals.load
-        count = Access::PopulationDiscovery.new.call.candidates.count do |candidate|
+        Access::PopulationDiscovery.new.call.candidates.select do |candidate|
           candidate.principal_source && !record.approved?(candidate.model_name, candidate.method_name)
         end
-        count.positive? ? count : nil
       rescue StandardError
-        nil
+        []
       end
 
       def mutate_browser_identity(env, params, browser_identity)
@@ -311,9 +284,9 @@ module Karst
         end
       end
 
-      def browser_token(browser_identity)
-        browser_identity.token if Identity.browser_supported?
-      rescue Identity::Error
+      def csrf_token(csrf)
+        csrf.token
+      rescue Csrf::InvalidToken
         nil
       end
 
@@ -363,8 +336,7 @@ module Karst
           nil
         end
 
-        # Mirrors Karst::Spec::Observer's own treatment of request paths: a
-        # query string can carry a token (password reset, OAuth callback,
+        # A query string can carry a token (password reset, OAuth callback,
         # signed URL), and this path is only ever contextual display evidence
         # in the panel, never route identity, so it is never worth the risk.
         def strip_query(value)