karst 0.1.0 → 0.4.0

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,10 +19,11 @@ 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"
+require_relative "../cli/reproduction"
 
 module Karst
   module Web
@@ -52,9 +54,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,17 +84,48 @@ 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)
+        reproduction, denied = reproduction_result(env, params, csrf)
+        return denied if denied
+
+        # Every local-state write this request may make (selection,
+        # approval) has happened by now, so one snapshot of the effective
+        # identity configuration serves the analysis, discovery, and the
+        # whole page render -- never one resolution per rendered user.
+        #
+        # `record` and `discovery` are this request's one approval-file read
+        # and one population-discovery pass, shared with whatever inside
+        # Identity.snapshot itself confirms already-approved populations
+        # (Access::ApprovedPopulations.merge) as well as with
+        # #inline_population_candidates below -- so a request that finds no
+        # usable outcome and goes on to look for candidate populations still
+        # reads the approval file, and parses model source, exactly once.
+        # `discovery`'s own principal_sources is a callable rather than a
+        # value because it is only ever actually needed by a *full* discovery
+        # pass (#inline_population_candidates), never by confirming one
+        # already-approved scope (which Identity.snapshot triggers first) --
+        # so by the time it is called, `identity` already holds this
+        # request's one resolution and nothing here re-resolves it.
+        record = Access::PopulationApprovals.load
+        identity = nil
+        discovery = Access::PopulationDiscovery.new(principal_sources: -> { identity.principal_sources })
+        identity = Identity.snapshot(record: record, discovery: discovery)
+        result = analyze(env, params, identity, approval: approval)
+        candidates = inline_population_candidates(result, record: record, discovery: discovery)
         Panel.render(params: params, access_result: result, route_lookup_limitation: lookup&.limitation,
-                     csrf_token: browser_token(browser_identity),
-                     browser_identity_active: browser_identity_active?(browser_identity),
-                     unapproved_candidate_count: unapproved_candidate_count(result),
+                     csrf_token: csrf_token(csrf), identity_snapshot: identity,
+                     browser_identity_active: browser_identity_active?(browser_identity, identity),
+                     unapproved_candidates: candidates, population_approval_error: approval&.error,
                      principal_source_selection_saved: !selection.nil? && selection.error.nil?,
-                     principal_source_selection_error: selection&.error)
+                     principal_source_selection_error: selection&.error, reproduction: reproduction)
       end
       # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
@@ -119,6 +149,83 @@ module Karst
         env["REQUEST_METHOD"] == "POST" && params["operation"] == "select_principal_sources"
       end
 
+      # [evidence_document, nil], or [nil, forbidden_response]. Unlike the
+      # access sweep -- which only ever issues GET requests the developer
+      # could have made in their own browser -- reproduction issues one
+      # caller-specified request that may mutate, enqueue, and send mail, so
+      # it is protected exactly like the two operations that write local
+      # state: same-origin plus Karst's own CSRF token.
+      def reproduction_result(env, params, csrf)
+        return [nil, nil] unless env["REQUEST_METHOD"] == "POST" && params["operation"] == "reproduce_request"
+        return [nil, forbidden] unless approved_origin?(env)
+
+        csrf.verify!(params["csrf_token"])
+        [reproduce(env, params), nil]
+      rescue Csrf::InvalidToken
+        [nil, forbidden]
+      rescue ArgumentError => e
+        [{ schema_version: 1, error: { type: "input_error", message: e.message } }, nil]
+      end
+
+      def reproduce(env, params)
+        Karst::CLI::Reproduction.new(
+          path: params["path"], http_method: params["method"], body: params["body"],
+          content_type: params["content_type"], headers: request_headers(params["headers"]),
+          base_url: base_url(env)
+        ).evidence
+      end
+
+      # "Name: value" per line. A line Karst cannot read as a header is
+      # refused outright rather than silently dropped -- a header quietly
+      # missing from the request would make every observation below it wrong.
+      def request_headers(value)
+        value.to_s.split("\n").each_with_object({}) do |line, result|
+          next if line.strip.empty?
+
+          name, header_value = line.split(":", 2)
+          raise ArgumentError, "expected one header per line, as \"Name: value\"" if header_value.nil?
+
+          result[name.strip] = header_value.strip
+        end
+      end
+
+      # The developer's own origin, so a copied command runs against the
+      # server they are already looking at. Never a deployed host: Karst only
+      # ever knows about this local request.
+      def base_url(env)
+        request = Rack::Request.new(env)
+        "#{request.scheme}://#{request.host_with_port}"
+      end
+
+      # Validating and saving a submitted approval needs the effective
+      # principal sources *before* the write (to confirm the submitted
+      # candidates are currently real), so this necessarily resolves
+      # configuration once on its own -- separately from the fresh
+      # post-write resolution #call_owned takes afterward to render. `record`
+      # and `discovery` are still shared between the two config reads this
+      # one pre-write resolution would otherwise need (confirming
+      # already-approved populations, then discovering current candidates to
+      # validate the submission against), so this method itself reads the
+      # approval file and parses model source exactly once.
+      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"])
+        [validate_population_approval(params), nil]
+      rescue Csrf::InvalidToken, Identity::Error
+        [nil, forbidden]
+      end
+
+      def validate_population_approval(params)
+        record = Access::PopulationApprovals.load
+        sources = nil
+        discovery = Access::PopulationDiscovery.new(principal_sources: -> { sources })
+        sources = Identity.principal_sources(record: record, discovery: discovery)
+        Access::PopulationApproval.new(discovery: discovery.call, principal_sources: sources,
+                                       submitted: params["population"], record: record).call
+      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 +237,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 +292,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,32 +326,30 @@ 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, identity, 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
+                           sources: identity.principal_sources!).call
       rescue Access::Error, Identity::Error, ArgumentError => e
         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, record:, discovery:)
+        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|
+        discovery.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,14 +373,14 @@ 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
 
-      def browser_identity_active?(browser_identity)
-        Identity.browser_supported? && browser_identity.active?
+      def browser_identity_active?(browser_identity, identity)
+        identity.browser_supported? && browser_identity.active?
       rescue Identity::Error
         false
       end
@@ -363,8 +425,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)