karst 0.1.0

data/lib/karst/spec/scenario.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Karst
+  module Spec
+    # One RSpec example exercising one specific browser-facing controller/action
+    # request, built entirely from evidence already present in the JSON artifact
+    # Karst::Spec::Observer writes.
+    #
+    # `observed_status`/`observed_redirect` describe what this spec execution
+    # observed while it ran, never what the example asserted -- a failing or
+    # pending example still produces a Scenario, and `example_outcome` is how
+    # a consumer tells "verified" apart from "merely observed."
+    #
+    # An example that issues several browser-facing requests (a denied attempt
+    # followed by an allowed retry, a sign-in followed by the page it unlocks)
+    # legitimately produces one Scenario per such request: Karst never
+    # collapses an example down to "its last request," and never labels any
+    # request as authentication setup versus the subject under test.
+    #
+    # `principal_before`/`principal_after` are both kept, not collapsed to
+    # whichever was active when the request began: a signup or checkout
+    # scenario that establishes a session is exactly the case where the
+    # identity a request produces matters as much as the identity it started
+    # with, and either side alone would discard real evidence.
+    Scenario = Value.define(
+      :example_id,
+      :file_path,
+      :line_number,
+      :description_parts,
+      :full_description,
+      :karst_explicit,
+      :karst_name,
+      :example_outcome,
+      :controller,
+      :action,
+      :http_method,
+      :route_pattern,
+      :observed_path,
+      :observed_status,
+      :observed_redirect,
+      :principal_before,
+      :principal_after,
+      :principal_changed,
+      :sequence
+    ) do
+      # The most specific zero-config name available without repeating the
+      # whole describe chain: RSpec's own nesting already puts the most
+      # specific description last. Never invents a persona the spec itself
+      # did not name.
+      def name
+        karst_name || description_parts.last || full_description
+      end
+
+      def passed?
+        example_outcome == :passed
+      end
+
+      def explicit?
+        karst_explicit
+      end
+    end
+  end
+end

data/lib/karst/value.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Karst
+  # Small immutable value-object helper standing in for Ruby 3.2's
+  # Data.define, which Karst cannot rely on while supporting Ruby 2.7. Built
+  # on Struct(keyword_init: true), which already provides structural
+  # equality, keyword construction, and #members; the one thing Struct does
+  # not give for free is immutability, so .define freezes every instance its
+  # class produces. This matches Data's own contract exactly: the instance
+  # itself is frozen, but a member holding a mutable object (an Array, say)
+  # is not deep-frozen -- Data.define does not do that either, and Karst does
+  # not need it to.
+  module Value
+    # rubocop:disable Naming/BlockForwarding, Style/ArgumentsForwarding -- anonymous
+    # block forwarding (`&`) needs Ruby 3.1; this file runs on Ruby 2.7.
+    def self.define(*members, &block)
+      klass = Struct.new(*members, keyword_init: true, &block)
+      # rubocop:enable Naming/BlockForwarding, Style/ArgumentsForwarding
+
+      # Struct.new itself is a heavily overloaded class method (it doubles as
+      # the anonymous-subclass factory), so overriding it and calling super
+      # would climb straight past Struct's own keyword-init handling into
+      # that factory instead of a plain constructor. Overriding the ordinary
+      # instance method #initialize has no such trap.
+      klass.class_eval do
+        def initialize(...)
+          super
+          freeze
+        end
+      end
+
+      klass
+    end
+  end
+end

data/lib/karst/version.rb

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

data/lib/karst/web/badge.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # Route identity (controller/action/http_method) comes from
+    # Middleware, itself derived from a real process_action.action_controller
+    # notification; Badge never infers it from a path. `context.path` is
+    # carried along purely as display context for the panel (see
+    # Karst::Web::Panel), never as part of route identity.
+    module Badge
+      Context = Struct.new(:controller, :action, :http_method, :path, keyword_init: true)
+
+      # A generous ceiling, not a tuning knob: real pages are a few hundred KB
+      # at most, and this exists only to decline joining a body large enough
+      # that string-splicing it would be wasteful, not to police page weight.
+      MAX_INJECTABLE_BYTES = 5 * 1024 * 1024
+      private_constant :MAX_INJECTABLE_BYTES
+
+      BODY_CLOSE_TAG = %r{</body>}i
+      private_constant :BODY_CLOSE_TAG
+
+      # `all:initial` strips whatever the host page's own CSS would otherwise
+      # inherit onto the badge (fonts, colors, positioning contexts); every
+      # property Karst actually wants is re-declared afterward in the same
+      # attribute, so the cascade only ever sees Karst's own values.
+      BADGE_STYLE =
+        "all:initial;position:fixed;bottom:12px;right:12px;z-index:2147483647;" \
+        "display:inline-block;padding:.35rem .65rem;border-radius:999px;" \
+        "background:#202124;color:#fff;font:600 12px/1.4 -apple-system,system-ui,sans-serif;" \
+        "text-decoration:none;box-shadow:0 1px 4px rgba(0,0,0,.35)"
+      private_constant :BADGE_STYLE
+
+      class << self
+        # Returns a replacement [status, headers, body] triple, or nil when
+        # the response should be returned to the host application unchanged
+        # -- including when anything above raises, so a bug here can never
+        # turn into a broken host page.
+        def apply(status:, headers:, body:, context:)
+          return nil unless context
+          return nil unless html_response?(status: status, headers: headers)
+          # `to_ary` is Rack's own signal that a body is already fully
+          # buffered rather than genuinely streaming (Rack::ETag relies on
+          # exactly this same check for exactly this same reason). Rails
+          # delegates it down to the response's real stream object, so a
+          # Live-streaming response correctly reports false and is left
+          # alone. Under Rack 2 (Rails 7.0), ActionDispatch's older
+          # RackBody wrapper never exposes to_ary at all -- every response
+          # reports false there, so Badge never injects on that Rails
+          # series. That is a missing feature, not a bug: guessing
+          # bufferability by any other means risks blocking forever on a
+          # real streaming body, which this module will not do.
+          return nil unless body.respond_to?(:to_ary)
+
+          parts = body.to_ary
+          return nil unless bufferable?(parts)
+
+          rewrite(status: status, headers: headers, parts: parts, body: body, context: context)
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def html_response?(status:, headers:)
+          return false unless status.is_a?(Integer) && status >= 200 && status < 300
+          return false if header(headers, "content-disposition")
+          return false if content_encoded?(headers)
+
+          header(headers, "content-type").to_s.downcase.start_with?("text/html")
+        end
+
+        def content_encoded?(headers)
+          encoding = header(headers, "content-encoding").to_s.strip
+          !encoding.empty? && !encoding.casecmp?("identity")
+        end
+
+        def bufferable?(parts)
+          parts.is_a?(Array) && parts.all?(String) && parts.sum(&:bytesize) <= MAX_INJECTABLE_BYTES
+        end
+
+        def rewrite(status:, headers:, parts:, body:, context:)
+          original = parts.join
+          index = original.rindex(BODY_CLOSE_TAG)
+          return nil unless index
+
+          html = "#{original[0...index]}#{markup(headers: headers, context: context)}#{original[index..]}"
+          new_headers = headers.dup
+          set_content_length!(new_headers, html.bytesize)
+          strip_validators!(new_headers)
+          body.close if body.respond_to?(:close)
+          [status, new_headers, [html]]
+        end
+
+        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>"
+        end
+
+        def query_for(context)
+          Rack::Utils.build_query(
+            "controller" => context.controller, "action" => context.action,
+            "method" => context.http_method, "path" => context.path
+          )
+        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
+        # under a policy with no 'unsafe-inline'.
+        def inline_style_allowed?(headers)
+          csp = header(headers, "content-security-policy").to_s.strip
+          return true if csp.empty?
+
+          directives = csp.split(";").map(&:strip)
+          directive = directives.find { |item| item.start_with?("style-src") } ||
+                      directives.find { |item| item.start_with?("default-src") }
+          directive.nil? || directive.include?("'unsafe-inline'")
+        end
+
+        def header(headers, name)
+          key = headers.keys.find { |candidate| candidate.to_s.casecmp?(name) }
+          key && headers[key]
+        end
+
+        def set_content_length!(headers, bytesize)
+          key = headers.keys.find { |candidate| candidate.to_s.casecmp?("content-length") }
+          headers[key || "content-length"] = bytesize.to_s
+        end
+
+        # ETag/Last-Modified validate a specific byte sequence; once Karst
+        # appends the badge, any validator computed on the host's original
+        # body no longer describes what is actually being served. Dropping
+        # them is safer than emitting a validator Karst never recomputed.
+        def strip_validators!(headers)
+          %w[etag last-modified].each do |name|
+            key = headers.keys.find { |candidate| candidate.to_s.casecmp?(name) }
+            headers.delete(key) if key
+          end
+        end
+
+        def escape(value)
+          CGI.escapeHTML(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/karst/web/browser_identity.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "uri"
+require "active_support/security_utils"
+
+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.
+    class BrowserIdentity
+      TOKEN_KEY = "karst.csrf_token"
+      ACTIVE_KEY = "karst.browser_identity_active"
+
+      # The exact Devise/Warden scope the currently assumed identity was
+      # established under (see Identity.assume_browser), retained for the
+      # lifetime of the browser session so #clear can hand it straight back
+      # to Identity.clear_browser instead of that having to guess which of
+      # several selected sources produced the principal being cleared.
+      SCOPE_KEY = "karst.browser_identity_scope"
+
+      def initialize(request)
+        @request = request
+      end
+
+      def token
+        session[TOKEN_KEY] ||= SecureRandom.hex(32)
+      end
+
+      def active?
+        session[ACTIVE_KEY] == true
+      end
+
+      def assume(params)
+        verify_token!(params["csrf_token"])
+        target = return_path(params["path"])
+        principal = Identity.resolve(model_name: params["principal_type"], id: params["principal_id"])
+        raise Identity::Unavailable, "principal is not in the configured source" unless principal
+
+        scope = Identity.assume_browser(@request, principal)
+        # Authentication hooks may clear or replace the host session. Rebuild
+        # Karst's control state only after that transition, and invalidate the
+        # token which authorized it rather than carrying pre-assumption state
+        # into the assumed identity.
+        session[ACTIVE_KEY] = true
+        session[SCOPE_KEY] = scope&.to_s
+        rotate_token!
+        target
+      end
+
+      def clear(params)
+        verify_token!(params["csrf_token"])
+        target = return_path(params["path"])
+        scope = session[SCOPE_KEY]
+        Identity.clear_browser(@request, scope: scope&.to_sym)
+        session.delete(ACTIVE_KEY)
+        session.delete(SCOPE_KEY)
+        target
+      end
+
+      private
+
+      def session
+        @request.session
+      rescue StandardError
+        raise Identity::Unavailable, "a writable Rack session is required"
+      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
+      end
+
+      def rotate_token!
+        session[TOKEN_KEY] = SecureRandom.hex(32)
+      end
+
+      # A blank path is not a caller error: the panel renders this same
+      # hidden field for "Stop testing as" from a plain /karst visit with no
+      # ?path= in the query string (bookmarked, or reached without a route
+      # already selected) -- exactly what happens right after Test As
+      # navigates the browser away to the tested page and a developer comes
+      # back to /karst directly. Falling back to /karst itself keeps that
+      # button working instead of raising and leaving the assumed identity
+      # active.
+      def return_path(value)
+        return "/karst" if value.to_s.empty?
+
+        raw = value.to_s.split("?", 2).first
+        uri = URI.parse(raw)
+        valid = uri.relative? && raw.start_with?("/") && !raw.start_with?("//")
+        raise Identity::Unavailable, "return path must be a local application path" unless valid
+
+        raw
+      rescue URI::InvalidURIError
+        raise Identity::Unavailable, "return path must be a valid local application path"
+      end
+    end
+  end
+end

data/lib/karst/web/locality.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Karst
+  module Web
+    # Determines whether a Rack peer is local without consulting proxy headers.
+    # WSL's NAT makes a Windows browser appear as the Linux VM's default gateway,
+    # so that one address is accepted when the process is verifiably running in
+    # WSL. Other private-network peers remain untrusted.
+    class Locality
+      LOOPBACK_RANGES = [IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")].freeze
+      private_constant :LOOPBACK_RANGES
+
+      def initialize(environment: ENV, osrelease_path: "/proc/sys/kernel/osrelease", route_path: "/proc/net/route")
+        @environment = environment
+        @osrelease_path = osrelease_path
+        @route_path = route_path
+      end
+
+      def local?(remote_address)
+        address = IPAddr.new(remote_address.to_s)
+        loopback?(address) || wsl_gateway == address
+      rescue IPAddr::Error
+        false
+      end
+
+      private
+
+      def loopback?(address)
+        LOOPBACK_RANGES.any? { |range| range.include?(address) }
+      end
+
+      def wsl_gateway
+        return unless wsl?
+
+        gateway_address(default_gateway_hex)
+      rescue Errno::ENOENT, Errno::EACCES, IPAddr::Error
+        nil
+      end
+
+      def default_gateway_hex
+        route = File.foreach(@route_path).drop(1).find do |line|
+          fields = line.split
+          fields[1] == "00000000" && fields[3].to_i(16).anybits?(0x2)
+        end
+        route&.split&.fetch(2, nil)
+      end
+
+      def gateway_address(hex)
+        return unless hex&.match?(/\A[0-9A-Fa-f]{8}\z/)
+
+        IPAddr.new([hex].pack("H*").reverse.unpack("C4").join("."))
+      end
+
+      def wsl?
+        @environment.key?("WSL_INTEROP") || @environment.key?("WSL_DISTRO_NAME") ||
+          File.read(@osrelease_path).match?(/microsoft|wsl/i)
+      rescue Errno::ENOENT, Errno::EACCES
+        false
+      end
+    end
+  end
+end