sentiero 1.0.0.alpha1

data/lib/sentiero/redaction/config.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Redaction
+    # Operator-facing redaction settings. The declarative subset serializes to
+    # the client (to_client_hash) and drives both engines; dom_patterns and
+    # server_proc are server-only.
+    class Config
+      attr_accessor :server_proc
+      attr_reader :url_mode, :disabled_patterns, :custom_patterns, :dom_patterns
+
+      URL_MODE_TO_CLIENT = {strip: "strip", keep_all: "keepAll", keep_filtered: "keepFiltered"}.freeze
+      URL_MODE_FROM_CLIENT = URL_MODE_TO_CLIENT.invert.freeze
+
+      def self.from_client_hash(hash)
+        hash ||= {}
+        new(
+          url_mode: URL_MODE_FROM_CLIENT.fetch(hash["urlMode"], :strip),
+          url_param_allowlist: hash["urlParamAllowlist"] || [],
+          url_param_denylist: hash["urlParamDenylist"] || [],
+          disabled_patterns: (hash["disabledPatterns"] || []).map(&:to_sym),
+          custom_patterns: (hash["customPatterns"] || []).map { |s| Regexp.new(s) }
+        )
+      end
+
+      def initialize(url_mode: :strip, url_param_allowlist: [], url_param_denylist: [], disabled_patterns: [], custom_patterns: [], dom_patterns: [], server_proc: nil)
+        @url_mode = url_mode
+        @url_param_allowlist = url_param_allowlist
+        @url_param_denylist = url_param_denylist
+        @disabled_patterns = disabled_patterns
+        @custom_patterns = custom_patterns
+        # Symbols so `TEXT_PATTERN_ORDER - dom_patterns` in redact_dom_event works
+        # even when an operator passes pattern names as strings.
+        @dom_patterns = dom_patterns.map(&:to_sym)
+        @server_proc = server_proc
+      end
+
+      def active_text_patterns
+        TEXT_PATTERN_ORDER - disabled_patterns
+      end
+
+      def effective_allowlist
+        @url_param_allowlist.map(&:downcase)
+      end
+
+      def effective_denylist
+        (BUILTIN_DENYLIST + @url_param_denylist.map(&:downcase)).uniq
+      end
+
+      def to_client_hash
+        {
+          urlMode: URL_MODE_TO_CLIENT.fetch(url_mode, "strip"),
+          urlParamAllowlist: effective_allowlist,
+          urlParamDenylist: effective_denylist,
+          disabledPatterns: disabled_patterns.map(&:to_s),
+          customPatterns: custom_patterns.map(&:source)
+        }
+      end
+    end
+  end
+end

data/lib/sentiero/redaction.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "redaction/config"
+
+module Sentiero
+  # Redaction engine for side-channel capture (navigation, form_submit,
+  # metadata, error, click) that bypasses rrweb input masking. Must stay
+  # byte-for-byte equivalent to the JS twin frontend/src/redaction.js;
+  # test/fixtures/redaction_cases.json pins that parity.
+  module Redaction
+    REDACTED = "[redacted]"
+
+    # Fixed application order, identical to the JS module.
+    TEXT_PATTERN_ORDER = %i[url jwt email long_hex card].freeze
+
+    TEXT_PATTERNS = {
+      jwt: /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/,
+      email: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/,
+      long_hex: /\b[0-9a-fA-F]{32,}\b/,
+      card: /\b\d(?:[ -]?\d){12,18}\b/
+    }.freeze
+
+    URL_IN_TEXT = %r{https?://\S+}
+
+    BUILTIN_DENYLIST = %w[
+      token access_token refresh_token id_token password passwd pwd secret
+      api_key apikey key sig signature code auth session sessionid otp
+    ].freeze
+
+    CUSTOM_EVENT_TYPE = 5
+    META_EVENT_TYPE = 4
+
+    URL_METADATA_KEYS = %w[url referrer entry_url entry_referrer].freeze
+
+    # tag => { "field" => :url|:text }
+    CUSTOM_FIELD_MAP = {
+      "navigation" => {"url" => :url, "text" => :text},
+      "__form_submit" => {"url" => :url},
+      "error" => {"message" => :text, "stack" => :text, "source" => :url},
+      "__click" => {"selector" => :text}
+    }.freeze
+
+    module_function
+
+    def redact_url(url, config = Config.new)
+      return url unless url.is_a?(String)
+
+      case config.url_mode
+      when :keep_all then url
+      when :keep_filtered then filter_url(url, config)
+      else strip_url_string(url)
+      end
+    end
+
+    def redact_text(value, config = Config.new)
+      return value unless value.is_a?(String)
+
+      out = value
+      config.active_text_patterns.each do |name|
+        out = apply_text_pattern(out, name)
+      end
+      config.custom_patterns.each { |re| out = out.gsub(re, REDACTED) }
+      out
+    end
+
+    def redact_event(event, config = Config.new)
+      return event unless event.is_a?(Hash)
+
+      if event["type"] == CUSTOM_EVENT_TYPE && event["data"].is_a?(Hash)
+        redact_custom_event(event, config)
+      elsif event["type"] == META_EVENT_TYPE && event["data"].is_a?(Hash)
+        redact_meta_event(event, config)
+      else
+        redact_dom_event(event, config)
+      end
+    end
+
+    def redact_metadata(metadata, config = Config.new)
+      return metadata unless metadata.is_a?(Hash)
+
+      metadata.to_h do |key, value|
+        if URL_METADATA_KEYS.include?(key)
+          [key, redact_url(value, config)]
+        else
+          [key, deep_redact_strings(value, config)]
+        end
+      end
+    end
+
+    def apply_text_pattern(text, name)
+      if name == :url
+        text.gsub(URL_IN_TEXT) { |m| strip_url_string(m) }
+      else
+        text.gsub(TEXT_PATTERNS.fetch(name), REDACTED)
+      end
+    end
+
+    def filter_url(url, config)
+      base, query, frag = split_url(url)
+      pairs = query.empty? ? [] : query.split("&").filter_map { |p| filter_param(p, config) }
+      out = base
+      out += "?#{pairs.join("&")}" unless pairs.empty?
+      out += "##{redact_text(frag, config)}" unless frag.empty?
+      out
+    end
+
+    def filter_param(pair, config)
+      eq = pair.index("=")
+      name = (eq ? pair[0...eq] : pair).downcase
+      # Denylist wins over the allowlist so allowlisting a built-in secret name
+      # (token/password/...) can't re-enable persisting it.
+      return nil if config.effective_denylist.include?(name)
+      return pair if config.effective_allowlist.include?(name)
+      return pair unless eq
+
+      # Match patterns against the decoded value (email=user%40example.com must
+      # be caught the same as email=user@example.com) but only substitute when
+      # something actually matched; a clean survivor keeps its original,
+      # unmodified encoding rather than being needlessly re-encoded.
+      raw_value = pair[(eq + 1)..]
+      decoded = url_decode(raw_value)
+      redacted = redact_text(decoded, config)
+      (redacted == decoded) ? pair : "#{pair[0...eq]}=#{redacted}"
+    end
+
+    # Plain percent-decode (leaves "+" alone, unlike www-form decoding). Falls
+    # back to the raw value on malformed escapes or invalid UTF-8 rather than
+    # raising, since this parses attacker-controlled URLs from public events.
+    def url_decode(value)
+      decoded = URI::RFC2396_PARSER.unescape(value)
+      decoded.valid_encoding? ? decoded : value
+    end
+
+    # Manual split (not URI) so JS and Ruby behave identically on edge cases.
+    def split_url(url)
+      base = url
+      frag = ""
+      if (h = base.index("#"))
+        frag = base[(h + 1)..]
+        base = base[0...h]
+      end
+      query = ""
+      if (q = base.index("?"))
+        query = base[(q + 1)..]
+        base = base[0...q]
+      end
+      [base, query, frag]
+    end
+
+    def strip_url_string(url)
+      cut = url.index("?") || url.length
+      hash = url.index("#")
+      cut = hash if hash && hash < cut
+      url[0...cut]
+    end
+
+    def redact_custom_event(event, config)
+      map = CUSTOM_FIELD_MAP[event["data"]["tag"]]
+      payload = event["data"]["payload"]
+      return event unless payload.is_a?(Hash)
+
+      # Mapped fields use their url/text treatment; every other field (and every
+      # field of an unmapped tag) is deep-redacted rather than stored raw, so a
+      # buggy/hostile client can't smuggle PII through an unmapped key.
+      new_payload = payload.to_h do |k, v|
+        case map&.dig(k)
+        when :url then [k, redact_url(v, config)]
+        when :text then [k, redact_text(v, config)]
+        else [k, deep_redact_strings(v, config)]
+        end
+      end
+      event.merge("data" => event["data"].merge("payload" => new_payload))
+    end
+
+    # DOM text/data is left alone unless the operator opts in.
+    def redact_dom_event(event, config)
+      return event if config.dom_patterns.empty? && config.custom_patterns.empty?
+      return event unless event["data"]
+
+      dom_cfg = Config.new(disabled_patterns: TEXT_PATTERN_ORDER - config.dom_patterns,
+        custom_patterns: config.custom_patterns)
+      event.merge("data" => deep_redact_strings(event["data"], dom_cfg))
+    end
+
+    # rrweb Meta events (type 4) carry the full page URL in data.href, which
+    # bypasses rrweb's own input masking entirely; always URL-redact it like
+    # any other structural URL field (navigation.url, error.source, ...).
+    def redact_meta_event(event, config)
+      return event unless event["data"].key?("href")
+
+      event.merge("data" => event["data"].merge("href" => redact_url(event["data"]["href"], config)))
+    end
+
+    def deep_redact_strings(value, config)
+      case value
+      when String then redact_text(value, config)
+      when Array then value.map { |v| deep_redact_strings(v, config) }
+      when Hash
+        # Keys can carry PII too (e.g. a caller using an email as a hash key);
+        # redact them the same as values. Last-write-wins on key collisions.
+        value.to_h { |k, v| [deep_redact_strings(k, config), deep_redact_strings(v, config)] }
+      else value
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "scrubber"
+
+module Sentiero
+  module Reporter
+    class Configuration
+      attr_accessor :endpoint, :ingest_key, :project, :environment, :release,
+        :default_filter_keys, :filter_keys, :enabled, :async, :max_queue,
+        :open_timeout, :read_timeout,
+        :session_cookie_name, :window_cookie_name,
+        :transport,
+        :before_notify
+
+      attr_reader :ignore_exceptions
+
+      def initialize
+        @endpoint = nil
+        @ingest_key = nil
+        @project = nil
+        @environment = nil
+        @release = nil
+        @default_filter_keys = Scrubber::DEFAULT_KEYS.dup
+        @filter_keys = []
+        @enabled = true
+        @async = true
+        @max_queue = 100
+        @open_timeout = 2
+        @read_timeout = 3
+        @session_cookie_name = "sentiero_sid"
+        @window_cookie_name = "sentiero_wid"
+        @transport = nil
+        @ignore_exceptions = []
+        @before_notify = nil
+      end
+
+      def ignore_exceptions=(value)
+        @ignore_exceptions = Array(value)
+      end
+
+      def configured?
+        !endpoint.nil? && !ingest_key.nil? && !project.nil?
+      end
+
+      def active?
+        enabled && configured?
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/context.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "normalizer"
+
+module Sentiero
+  module Reporter
+    # Immutable, string-keyed bag of report context. Keys are normalized to
+    # strings on construction and on every merge.
+    class Context
+      def initialize(hash = {})
+        @data = Normalizer.stringify_shallow(hash).freeze
+      end
+
+      def merge(other)
+        Context.new(@data.merge(Normalizer.stringify_shallow(to_hash(other))))
+      end
+
+      def [](key) = @data[key.to_s]
+
+      def key?(key) = @data.key?(key.to_s)
+
+      def empty? = @data.empty?
+
+      def to_h = @data.dup
+
+      private
+
+      def to_hash(other) = other.is_a?(Context) ? other.to_h : other
+    end
+  end
+end

data/lib/sentiero/reporter/dispatcher.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "concurrent/atomic/atomic_fixnum"
+
+module Sentiero
+  module Reporter
+    # Delivers payloads to a transport, synchronously or via a bounded background
+    # queue. Never raises into the caller; when the async queue is full new
+    # payloads are dropped rather than blocking the host app.
+    class Dispatcher
+      # A latch pushed through the work queue by #flush; recognized by type.
+      FlushLatch = Thread::Queue
+
+      def dropped
+        @dropped.value
+      end
+
+      def initialize(transport, async:, max_queue:)
+        @transport = transport
+        @async = async
+        @dropped = Concurrent::AtomicFixnum.new(0) # incremented from concurrent enqueue callers
+        @rejection_warned = false
+        return unless @async
+
+        @queue = SizedQueue.new(max_queue)
+        @thread = Thread.new { run }
+        @thread.name = "sentiero-reporter" if @thread.respond_to?(:name=)
+      end
+
+      def enqueue(path, payload)
+        if @async
+          begin
+            @queue.push([path, payload], true) # non-block so ThreadError is raised if queue full
+          rescue ThreadError
+            @dropped.increment
+          end
+        else
+          deliver([path, payload])
+        end
+        nil
+      end
+
+      # Blocks until every payload enqueued before this call has been delivered.
+      # The latch rides the FIFO queue, so reaching it means all prior jobs are done.
+      def flush
+        return unless @async
+        latch = FlushLatch.new
+        @queue.push(latch)
+        latch.pop
+        nil
+      end
+
+      def shutdown
+        return unless @async
+        @queue.push(:stop)
+        @thread.join(2)
+      end
+
+      private
+
+      def run
+        loop do
+          job = @queue.pop
+          case job
+          when :stop then break
+          when FlushLatch then job.push(true) # prior jobs all delivered; wake #flush
+          else deliver(job)
+          end
+        end
+      end
+
+      def deliver((path, payload))
+        response = @transport.post(path, payload)
+        # Null/Log/Test transports return nil/arrays, not HTTP responses.
+        if response.respond_to?(:code) && !response.is_a?(Net::HTTPSuccess)
+          warn_rejected(response, path)
+        end
+      rescue => e
+        warn "[Sentiero::Reporter] delivery failed: #{e.class}: #{e.message}"
+      end
+
+      # First occurrence only (one dispatcher per process in practice.)
+      def warn_rejected(response, path)
+        return if @rejection_warned
+        @rejection_warned = true
+        warn "[Sentiero::Reporter] delivery rejected: HTTP #{response.code} for #{path}"
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/http_transport.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Sentiero
+  module Reporter
+    # Posts a JSON payload to "<endpoint>/<path>" with the ingest key as a Bearer token.
+    class HttpTransport
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+      def initialize(endpoint:, ingest_key:, open_timeout:, read_timeout:)
+        @endpoint = endpoint.to_s.sub(%r{/+\z}, "")
+        @ingest_key = ingest_key
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        warn_insecure_endpoint
+      end
+
+      def post(path, payload)
+        uri = URI.parse("#{@endpoint}/#{path}")
+        http = build_http(uri)
+
+        request = Net::HTTP::Post.new(uri)
+        request["content-type"] = "application/json"
+        request["authorization"] = "Bearer #{@ingest_key}"
+        request.body = JSON.generate(payload)
+
+        http.request(request)
+      end
+
+      private
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+        http
+      end
+
+      # The Bearer ingest key and payloads go in cleartext over http://; warn
+      # unless the endpoint is loopback (a common local-dev setup).
+      def warn_insecure_endpoint
+        uri = URI.parse(@endpoint)
+        return unless uri.scheme == "http"
+        return if LOOPBACK_HOSTS.include?(uri.host)
+
+        warn "[Sentiero::Reporter] endpoint #{@endpoint} uses http://; the ingest " \
+          "key and payloads are sent unencrypted. Use https://."
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/log_transport.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sentiero
+  module Reporter
+    # Transport that logs each delivery instead of sending it over the network.
+    class LogTransport
+      def initialize(io: $stderr, logger: nil, level: :info)
+        @io = io
+        @logger = logger
+        @level = level
+      end
+
+      def post(path, payload)
+        line = "[Sentiero::Reporter] #{path}: #{JSON.generate(payload)}"
+        if @logger
+          @logger.public_send(@level, line)
+        else
+          @io.puts(line)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/middleware.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+require_relative "../reporter"
+require_relative "../ip_anonymizer"
+
+module Sentiero
+  module Reporter
+    # Rack middleware that reports unhandled exceptions to Sentiero and re-raises
+    # them so the host app's own error handling is unaffected. Reads the recorder's
+    # session/window id cookies into the context so server exceptions link to the replay.
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Reporter.with_context(request_context(env)) do
+          @app.call(env)
+        rescue => e
+          Reporter.notify(e)
+          raise
+        end
+      end
+
+      private
+
+      def request_context(env)
+        cookies = Rack::Utils.parse_cookies(env)
+        ctx = {
+          request: {
+            "method" => env["REQUEST_METHOD"],
+            "path" => env["PATH_INFO"],
+            "params" => safe_parse_query(env["QUERY_STRING"]),
+            "ip" => client_ip(env)
+          }
+        }
+        sid = cookies[Reporter.configuration.session_cookie_name]
+        wid = cookies[Reporter.configuration.window_cookie_name]
+        ctx[:session_id] = sid if sid && !sid.empty?
+        ctx[:window_id] = wid if wid && !wid.empty?
+        ctx
+      rescue => e
+        warn "[Sentiero::Reporter] request_context failed: #{e.class}: #{e.message}"
+        {}
+      end
+
+      def safe_parse_query(query_string)
+        Rack::Utils.parse_nested_query(query_string)
+      rescue => _e
+        {}
+      end
+
+      def client_ip(env)
+        forwarded = env["HTTP_X_FORWARDED_FOR"]&.split(",")&.first&.strip
+        ip = (forwarded && !forwarded.empty?) ? forwarded : env["REMOTE_ADDR"]
+        anonymize = Sentiero.respond_to?(:configuration) && Sentiero.configuration.anonymize_ip
+        anonymize ? IpAnonymizer.anonymize(ip) : ip
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/normalizer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Reporter
+    module Normalizer
+      module_function
+
+      def stringify_shallow(hash)
+        return {} unless hash.is_a?(Hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/null_transport.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Reporter
+    class NullTransport
+      attr_reader :delivered
+
+      def initialize
+        @delivered = 0
+      end
+
+      def post(_path, _payload)
+        @delivered += 1
+        nil
+      end
+    end
+  end
+end

data/lib/sentiero/reporter/report_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Reporter
+    # Splits a Context into the reserved keys that become top-level fields on an
+    # error report (session_id, window_id) and the remaining metadata that goes
+    # under the report's "context".
+    class ReportContext
+      RESERVED = %w[session_id window_id].freeze
+
+      def initialize(context)
+        data = context.to_h
+        @reserved = {}
+        RESERVED.each do |key|
+          value = data.delete(key)
+          @reserved[key] = value unless value.nil?
+        end
+        @metadata = data
+      end
+
+      def session_id = @reserved["session_id"]
+
+      def window_id = @reserved["window_id"]
+
+      # Mutable so the caller can inject environment/release before scrubbing.
+      attr_reader :metadata
+    end
+  end
+end