allstak 0.1.1 → 0.2.1

data/lib/allstak/sanitizer.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+# AllStak Ruby SDK sanitizer.
+#
+# Provides recursive scrubbing of sensitive data across the full event surface
+# (user, extras, metadata, breadcrumbs.data, contexts, request, response).
+#
+# Two complementary layers run on the wire path:
+#
+#   1. KEY-NAME redaction (always on): a case-insensitive substring match on
+#      Hash keys against the canonical denylist. Conforms to the canonical
+#      AllStak SDK denylist defined in docs/standards/sdk-platform-standards.md.
+#
+#   2. VALUE-PATTERN redaction (Sentry data-scrubbing parity): scans free-text
+#      *string values* for PII that leaks regardless of key name. Two tiers:
+#        A) ALWAYS scrubbed — credit-card numbers that pass the Luhn checksum,
+#           and US SSNs written with hyphens. High-risk financial/identity data
+#           never legitimately wanted in telemetry.
+#        B) Scrubbed UNLESS send_default_pii — email addresses and IPv4
+#           addresses. Default send_default_pii=false matches Sentry.
+#
+# Semantics:
+# - Key match: case-insensitive substring match on Hash keys.
+# - Value replacement with the sentinel string `[REDACTED]` (key preserved).
+# - Recursion into Hash, Array; primitive values are passed through (with
+#   String values run through the value scrubbers per the rules above).
+# - Cycle protection via an object_id Set.
+# - Structural exemptions: certain keys/subtrees are never value-scrubbed
+#   (explicit user object, stack frames, release/sdk fields, URLs/paths,
+#   span/operation ids) — see VALUE_SCRUB_SKIP_KEYS / VALUE_SCRUB_SKIP_SUBTREES.
+# - Pure: returns a sanitized copy; never mutates caller-owned structures.
+# - Fail-open: value scrubbing never raises out of {.scrub}; on any error it
+#   falls back to the key-redacted-but-not-value-scrubbed structure.
+
+require "set"
+
+module AllStak
+  module Sanitizer
+    REDACTED = "[REDACTED]"
+
+    DEFAULT_DENYLIST = %w[
+      authorization
+      proxy-authorization
+      cookie
+      set-cookie
+      password
+      passwd
+      pwd
+      api_key
+      apikey
+      x-api-key
+      x-allstak-key
+      x-auth-token
+      x-access-token
+      token
+      bearer
+      jwt
+      session
+      sessionid
+      session_id
+      secret
+      credit_card
+      card_number
+      cvv
+      ssn
+      csrf
+    ].freeze
+
+    # Exact, CASE-SENSITIVE keys that look sensitive by substring but are NOT —
+    # they are first-class SDK telemetry fields that must survive scrubbing.
+    # The release-health `sessionId` (camelCase) carries the SDK's own
+    # per-process session id (a random UUID, not a user/auth session token);
+    # the backend error consumer needs it to attribute crashes, so it must
+    # never be redacted. Matched exactly and case-sensitively, so genuine
+    # cookie/auth keys like `session`, `session_id`, or `sessionid` (the
+    # lower-case denylist terms) are still scrubbed.
+    ALLOWLIST = %w[
+      sessionId
+    ].freeze
+
+    # --- value-pattern scrubbing configuration -----------------------------
+
+    # Longest single string we will scan for value patterns. Larger strings are
+    # passed through untouched so a pathological multi-MB blob never stalls the
+    # wire path. Key-name redaction still applies to its containing key.
+    MAX_SCAN_LENGTH = 16_384
+
+    # Keys whose *scalar* string value is exempt from value-pattern scrubbing
+    # (matched case-sensitively against the original key, then case-insensitively
+    # as a fallback). These carry structured identifiers / locations that the
+    # patterns would otherwise corrupt: stack-frame fields, release/sdk/build
+    # metadata, span & trace ids, URLs/paths (their own URL redactor owns them).
+    VALUE_SCRUB_SKIP_KEYS = %w[
+      filename
+      function
+      abspath
+      abs_path
+      lineno
+      colno
+      release
+      version
+      dist
+      platform
+      environment
+      sdkname
+      sdk_name
+      sdkversion
+      sdk_version
+      sdk.name
+      sdk.version
+      commit.sha
+      commit.branch
+      commit_sha
+      url
+      path
+      host
+      hostname
+      route
+      operation
+      op
+      spanid
+      span_id
+      parentspanid
+      parent_span_id
+      traceid
+      trace_id
+      requestid
+      request_id
+      sessionid
+      sessionId
+      timestamp
+    ].each_with_object({}) { |k, h| h[k.downcase] = true }.freeze
+
+    # Top-level subtrees that are never value-scrubbed. `user` holds data the
+    # caller explicitly set via setUser (intentional identification — ships as
+    # before, matching Sentry). `frames`/`stackTrace` hold structured stack
+    # frames whose filenames/functions must not be corrupted.
+    VALUE_SCRUB_SKIP_SUBTREES = %w[
+      user
+      frames
+      stackTrace
+      stacktrace
+    ].each_with_object({}) { |k, h| h[k.downcase] = true }.freeze
+
+    # US SSN — REQUIRE the hyphens so bare 9-digit numbers (order ids, etc.)
+    # are not nuked. Compiled once.
+    SSN_REGEX = /\b\d{3}-\d{2}-\d{4}\b/.freeze
+
+    # Candidate credit-card runs: 13–19 digits with optional single space/hyphen
+    # separators between groups. Luhn-validated before redaction (see #luhn?),
+    # so digit runs that fail the checksum (timestamps, order ids) survive.
+    # Word-boundary-ish anchors keep us from matching the middle of a longer
+    # digit string.
+    CC_CANDIDATE_REGEX = /(?<![\d-])(?:\d[ -]?){12,18}\d(?![\d-])/.freeze
+
+    # Standard email address. Compiled once.
+    EMAIL_REGEX = /\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b/.freeze
+
+    # IPv4 with each octet validated to 0–255. Compiled once.
+    IPV4_OCTET = '(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)'
+    IPV4_REGEX = /\b#{IPV4_OCTET}\.#{IPV4_OCTET}\.#{IPV4_OCTET}\.#{IPV4_OCTET}\b/.freeze
+
+    # IPv6 best-effort: 2+ groups of hex separated by colons, with optional ::
+    # compression. Intentionally loose — IPv6 detection is best-effort per spec.
+    IPV6_REGEX = /\b(?:[0-9A-Fa-f]{1,4}:){2,7}[0-9A-Fa-f]{0,4}\b|\b::(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4}\b/.freeze
+
+    module_function
+
+    # Returns a sanitized deep copy of `payload`.
+    #
+    # @param extra_denylist [Array<String>, nil] additional key terms to redact;
+    #   may extend but not narrow the canonical list.
+    # @param send_default_pii [Boolean] when true, the tier-B value scrubbers
+    #   (email, IPv4/IPv6) are disabled — the caller has opted into PII. Tier-A
+    #   (credit card, SSN) is ALWAYS applied. Default false (Sentry parity).
+    # @param values [Boolean] when false, only key-name redaction runs (no
+    #   value-pattern scrubbing). Useful for an intermediate pre-scrub (e.g.
+    #   Sidekiq job args) where the wire-path scrub will value-scrub later with
+    #   the authoritative config. Default true.
+    def scrub(payload, extra_denylist: nil, send_default_pii: false, values: true)
+      denylist = DEFAULT_DENYLIST.dup
+      denylist.concat(extra_denylist.map { |t| t.to_s.downcase }) if extra_denylist
+      denylist.uniq!
+      return walk_keys_only(payload, denylist, Set.new) unless values
+      walk(payload, denylist, Set.new, send_default_pii)
+    end
+
+    def sensitive?(key, denylist)
+      return false unless key.is_a?(String) || key.is_a?(Symbol)
+
+      # Exact, case-sensitive allowlist wins: a first-class SDK field (e.g.
+      # release-health `sessionId`) is never scrubbed even though its lowercase
+      # form contains a denied substring. Checked against the ORIGINAL key so
+      # `sessionId` survives while `sessionid`/`session_id`/`session` are scrubbed.
+      return false if ALLOWLIST.include?(key.to_s)
+
+      k = key.to_s.downcase
+      denylist.any? { |term| k.include?(term) }
+    end
+
+    def walk(value, denylist, seen, send_default_pii)
+      case value
+      when Hash
+        return REDACTED if seen.include?(value.object_id)
+
+        seen.add(value.object_id)
+        value.each_with_object({}) do |(k, v), out|
+          out[k] =
+            if sensitive?(k, denylist)
+              REDACTED
+            elsif skip_subtree?(k)
+              # Explicit user object / stack frames: deep-copy with key-name
+              # redaction still applied, but NO value-pattern scrubbing.
+              walk_keys_only(v, denylist, seen)
+            elsif skip_value_scrub_key?(k)
+              # Structured scalar (release, url, span id, …): recurse for nested
+              # collections, but do not value-scrub a scalar string here.
+              v.is_a?(Hash) || v.is_a?(Array) ? walk(v, denylist, seen, send_default_pii) : v
+            else
+              walk(v, denylist, seen, send_default_pii)
+            end
+        end
+      when Array
+        return REDACTED if seen.include?(value.object_id)
+
+        seen.add(value.object_id)
+        value.map { |v| walk(v, denylist, seen, send_default_pii) }
+      when String
+        scrub_value(value, send_default_pii)
+      else
+        value
+      end
+    end
+
+    # Recurse applying ONLY key-name redaction (no value-pattern scrubbing).
+    # Used for exempt subtrees (explicit user object, stack frames).
+    def walk_keys_only(value, denylist, seen)
+      case value
+      when Hash
+        return REDACTED if seen.include?(value.object_id)
+
+        seen.add(value.object_id)
+        value.each_with_object({}) do |(k, v), out|
+          out[k] = sensitive?(k, denylist) ? REDACTED : walk_keys_only(v, denylist, seen)
+        end
+      when Array
+        return REDACTED if seen.include?(value.object_id)
+
+        seen.add(value.object_id)
+        value.map { |v| walk_keys_only(v, denylist, seen) }
+      else
+        value
+      end
+    end
+
+    def skip_subtree?(key)
+      return false unless key.is_a?(String) || key.is_a?(Symbol)
+      VALUE_SCRUB_SKIP_SUBTREES.key?(key.to_s.downcase)
+    end
+
+    def skip_value_scrub_key?(key)
+      return false unless key.is_a?(String) || key.is_a?(Symbol)
+      VALUE_SCRUB_SKIP_KEYS.key?(key.to_s.downcase)
+    end
+
+    # Apply value-pattern scrubbing to a single string. Fail-open: any error
+    # returns the original string. Oversized strings are passed through.
+    def scrub_value(str, send_default_pii)
+      return str unless str.is_a?(String)
+      return str if str.empty? || str.length > MAX_SCAN_LENGTH
+
+      out = str
+
+      # Tier A — ALWAYS (regardless of send_default_pii).
+      out = out.gsub(SSN_REGEX, REDACTED)
+      out = scrub_credit_cards(out)
+
+      # Tier B — only when the caller has NOT opted into PII.
+      unless send_default_pii
+        out = out.gsub(EMAIL_REGEX, REDACTED)
+        out = out.gsub(IPV4_REGEX, REDACTED)
+        out = out.gsub(IPV6_REGEX, REDACTED)
+      end
+
+      out
+    rescue StandardError
+      str
+    end
+
+    # Replace only those candidate credit-card runs that pass the Luhn checksum.
+    # A run that fails Luhn (e.g. an order id or timestamp that happens to be
+    # 13–19 digits) is left intact, minimizing over-redaction.
+    def scrub_credit_cards(str)
+      str.gsub(CC_CANDIDATE_REGEX) do |match|
+        digits = match.gsub(/[ -]/, "")
+        if digits.length.between?(13, 19) && luhn?(digits)
+          REDACTED
+        else
+          match
+        end
+      end
+    end
+
+    # Luhn (mod-10) checksum over a string of digits.
+    def luhn?(digits)
+      return false unless digits =~ /\A\d{13,19}\z/
+
+      sum = 0
+      double = false
+      digits.reverse.each_char do |ch|
+        d = ch.to_i
+        if double
+          d *= 2
+          d -= 9 if d > 9
+        end
+        sum += d
+        double = !double
+      end
+      (sum % 10).zero?
+    end
+  end
+end

data/lib/allstak/session_tracker.rb

@@ -0,0 +1,216 @@
+require "securerandom"
+require_relative "transport/http_transport"
+
+module AllStak
+  # Server-mode "single session" release-health tracker.
+  #
+  # Mirrors the AllStak Java SDK `SessionTracker` lifecycle + status model:
+  # on {#start} the SDK posts a `/ingest/v1/sessions/start` envelope with the
+  # process's distinct session id, the resolved release, and SDK identity. On
+  # {#end} it posts `/ingest/v1/sessions/end` with the final status + total
+  # duration. ERRORED / CRASHED transitions are recorded in-memory only; only
+  # the terminal {#end} call performs network I/O for status, so per-error
+  # latency stays unaffected.
+  #
+  # One instance per {AllStak::Client}. Re-entrancy safe: once started a second
+  # {#start} is a no-op; once ended the tracker does not re-arm.
+  #
+  # Sessions are NEVER sampled — they are always sent (when tracking is on and a
+  # release is resolvable). The whole tracker is fully fail-open: a network
+  # failure or any other error must never crash app boot or shutdown.
+  class SessionTracker
+    PATH_START = "/ingest/v1/sessions/start".freeze
+    PATH_END   = "/ingest/v1/sessions/end".freeze
+
+    # Lifecycle status. Vocabulary matches the backend `/sessions/end` contract
+    # and Sentry's release-health conventions:
+    #   ok       — ended normally, at most non-fatal logs.
+    #   errored  — at least one HANDLED error captured; process kept running.
+    #   crashed  — an UNHANDLED/fatal exception ended the process.
+    #   abnormal — ended without a normal flush (reserved).
+    STATUS_OK       = "ok".freeze
+    STATUS_ERRORED  = "errored".freeze
+    STATUS_CRASHED  = "crashed".freeze
+    STATUS_ABNORMAL = "abnormal".freeze
+
+    attr_reader :session_id, :started_at
+
+    def initialize(config, transport, logger = nil)
+      @config = config
+      @transport = transport
+      @logger = logger
+      @mutex = Mutex.new
+      @session_id = nil
+      @started_at = nil
+      @status = STATUS_OK
+      @error_count = 0
+      @started = false
+      @ended = false
+    end
+
+    # Should this runtime track sessions at all? Off when the user opted out via
+    # `enable_auto_session_tracking = false`, and automatically off under a unit
+    # test runtime (mirrors the Java SDK's test guard) so the suite never emits
+    # session traffic.
+    def enabled?
+      return false unless @config.enable_auto_session_tracking
+      !self.class.test_runtime?
+    end
+
+    # Detect a unit-test runtime so session tracking self-disables there,
+    # matching {AllStak.register_runtime_release}'s own guard.
+    def self.test_runtime?
+      return true if ENV["MT_TEST"]
+      return true if ENV["RACK_ENV"] == "test" || ENV["RAILS_ENV"] == "test"
+      return true if ENV["RUBYOPT"].to_s.include?("minitest")
+      return true if $PROGRAM_NAME.to_s.include?("rspec")
+      defined?(Minitest) ? true : false
+    end
+
+    # Idempotent. Records sessionStart, sets in-memory status = "ok", and POSTs
+    # `/sessions/start` on a daemon thread so SDK init never blocks on a network
+    # round-trip. No-op when tracking is disabled, the transport is disabled, or
+    # no release/sdkVersion can be resolved. Never raises.
+    def start
+      @mutex.synchronize do
+        return self if @started
+        @started = true
+        @session_id = SecureRandom.uuid
+        @started_at = now_ms
+        @status = STATUS_OK
+        @error_count = 0
+      end
+
+      return self unless enabled?
+      return self if transport_disabled?
+
+      release = effective_release
+      return self if release.to_s.empty?
+
+      payload = {
+        sessionId:   @session_id,
+        release:     release,
+        environment: @config.environment,
+        userId:      current_user_id,
+        sdkName:     @config.sdk_name,
+        sdkVersion:  @config.sdk_version,
+        platform:    @config.platform
+      }.compact
+
+      send_async(PATH_START, payload, "session start")
+      self
+    end
+
+    # The active session id, or nil before start / after end. Attached to every
+    # error/event payload so the backend can mark the session errored/crashed.
+    def current_session_id
+      @mutex.synchronize { (@started && !@ended) ? @session_id : nil }
+    end
+
+    # Record a HANDLED error: bump status ok -> errored (never downgrades a
+    # terminal crash). No I/O.
+    def record_error
+      @mutex.synchronize do
+        next unless active_locked?
+        @error_count += 1
+        @status = STATUS_ERRORED if @status == STATUS_OK
+      end
+    end
+
+    # Record an UNHANDLED/fatal crash: terminal status (overrides errored).
+    # No I/O — the {#end} POST carries the status.
+    def record_crash
+      @mutex.synchronize do
+        next unless active_locked?
+        @error_count += 1
+        @status = STATUS_CRASHED
+      end
+    end
+
+    # Terminate the session and POST `/sessions/end` with durationMs + status.
+    # Idempotent. Best-effort with a short timeout; must not block or raise.
+    # `final_status` overrides the accumulated status when given.
+    def end(final_status = nil)
+      sid = nil
+      status = nil
+      duration = nil
+      @mutex.synchronize do
+        return if @ended || !@started
+        @ended = true
+        sid = @session_id
+        status = final_status || @status
+        duration = [now_ms - @started_at.to_i, 0].max
+      end
+
+      return unless enabled?
+      return if transport_disabled?
+      return if effective_release.to_s.empty?
+
+      payload = {
+        sessionId:  sid,
+        durationMs: clamp_int(duration),
+        status:     status
+      }.compact
+
+      send_sync(PATH_END, payload, "session end")
+    end
+
+    private
+
+    def active_locked?
+      @started && !@ended
+    end
+
+    def now_ms
+      (Time.now.to_f * 1000).to_i
+    end
+
+    def clamp_int(value)
+      v = value.to_i
+      v > 2_147_483_647 ? 2_147_483_647 : v
+    end
+
+    # Release is REQUIRED by the backend; fall back to the SDK version when no
+    # release is resolved so release-health attribution still has a key.
+    def effective_release
+      rel = @config.release
+      rel = @config.sdk_version if rel.to_s.empty?
+      rel
+    end
+
+    def current_user_id
+      uid = @config.respond_to?(:user_id) ? @config.user_id : nil
+      uid.to_s.empty? ? nil : uid.to_s
+    end
+
+    def transport_disabled?
+      @transport.respond_to?(:disabled?) && @transport.disabled?
+    rescue StandardError
+      false
+    end
+
+    # POST off the hot/boot path on a daemon thread. Fail-open.
+    def send_async(path, payload, label)
+      thread = Thread.new do
+        begin
+          @transport.post(path, payload)
+          @logger&.debug("[AllStak] #{label}: #{payload[:sessionId]}")
+        rescue StandardError => e
+          @logger&.debug("[AllStak] #{label} failed: #{e.class}: #{e.message}")
+        end
+      end
+      thread.abort_on_exception = false
+    rescue StandardError => e
+      @logger&.debug("[AllStak] #{label} could not start: #{e.class}: #{e.message}")
+    end
+
+    # Synchronous best-effort POST for shutdown — the process may exit before a
+    # background thread runs, so end is sent inline. Never raises.
+    def send_sync(path, payload, label)
+      @transport.post(path, payload)
+      @logger&.debug("[AllStak] #{label}: #{payload[:sessionId]} status=#{payload[:status]}")
+    rescue StandardError => e
+      @logger&.debug("[AllStak] #{label} failed: #{e.class}: #{e.message}")
+    end
+  end
+end