devbench 0.5.0

data/lib/devbench/scrub.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative 'fingerprint'
+
+module Devbench
+  # A port of the sidecar's strict egress (internal/scrub and
+  # Sidecar.forEgress): what direct mode does to an exemplar before it leaves
+  # the process, so leaving out the sidecar does not loosen redaction
+  # (DECISIONS #160). Held to testdata/redaction_vectors.json
+  # (test/redaction_vectors_test.rb).
+  #
+  # Strict mode is the only mode here: template (values the format marks:
+  # quoted strings, numbers, durations), then scrub (values with a shape:
+  # emails, cards, tokens, credentials, IPs), then the prose heuristic
+  # (runs of capitalised words that are not framework vocabulary).
+  #
+  # Patterns are Go's, with Go's \b and \s (see Fingerprint).
+  module Scrub
+    WS = Fingerprint::GO_WS
+    NOT_WS = Fingerprint::GO_NOT_WS
+
+    def self.go_re(source, options = 0)
+      Regexp.new(source.gsub('\b', Fingerprint::GO_B), options)
+    end
+    private_class_method :go_re
+
+    # Ordered most-specific first, and the order is load-bearing: see the
+    # comments on internal/scrub's rules (a credential containing an email,
+    # a phone pattern eating an SSN).
+    RULES = [
+      [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/, '<redacted:private-key>'],
+      [go_re('\beyJ[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\b'), '<redacted:jwt>'],
+      [go_re('([a-zA-Z][a-zA-Z0-9+.\-]*://)[^\t\n\f\r :/@]+:[^\t\n\f\r /@]+@'), '\1<redacted:credentials>@'],
+      [go_re("\\b(authorization|proxy-authorization)(#{WS}*[:=]#{WS}*)(?:#{NOT_WS}+[ \\t]+)?#{NOT_WS}+",
+             Regexp::IGNORECASE), '\1\2<redacted:authorization>'],
+      [go_re("\\b(bearer|basic)#{WS}+[A-Za-z0-9._\\-=/+]{8,}", Regexp::IGNORECASE), '\1 <redacted:token>'],
+      [go_re('\bAKIA[0-9A-Z]{16}\b'), '<redacted:aws-key>'],
+      [go_re('\b(password|passwd|pwd|secret|api[_\-]?key|access[_\-]?token|refresh[_\-]?token|' \
+             'client[_\-]?secret|private[_\-]?key|session[_\-]?id|csrf[_\-]?token)' \
+             "(#{WS}*[:=]#{WS}*)(\"[^\"]*\"|'[^']*'|#{NOT_WS}+)", Regexp::IGNORECASE), '\1\2<redacted:secret>'],
+      [go_re('\b[^\t\n\f\r <>@]+@[^\t\n\f\r <>@]+\.[A-Za-z]{2,}\b'), '<redacted:email>'],
+      [go_re('\b\d{3}-\d{2}-\d{4}\b'), '<redacted:ssn>'],
+      [go_re('\b(?:\d[ \-]*?){13,19}\b'), '<redacted:card>'],
+      [go_re('\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b'), '<redacted:ip>'],
+      [/\+?\d[\d\t\n\f\r ().\-]{7,}\d/, '<redacted:phone>']
+    ].freeze
+
+    # internal/sidecar/trace.go's traceRe.
+    TRACE = go_re('\bv1/([A-Za-z0-9_-]{1,64})/([A-Za-z0-9_-]{1,64})/(\d{1,3})\b')
+
+    # What Rails, Go and HTTP say, lowercased (internal/scrub/prose.go).
+    # Masking any of these would destroy diagnostic content.
+    VOCABULARY = %w[
+      ok created accepted content moved permanently found modified bad request
+      unauthorized payment required forbidden not method allowed acceptable
+      timeout conflict gone unsupported media type unprocessable entity too many
+      requests internal server error implemented gateway service unavailable no
+      see other temporary redirect
+      started completed processing rendered rendering redirected filter chain
+      halted parameters views load exists destroy update create transaction
+      rollback commit cache performed performing enqueued retrying rescued
+      validation failed invalid email has already been taken
+      panic goroutine runtime fatal context deadline exceeded canceled cancelled
+      connection refused such host timeout_ closed reset peer broken pipe
+      temporarily
+      warning warn info debug trace exception failure retry skipping unknown
+      missing expired denied true false nil null none
+    ].to_h { |w| [w, true] }.freeze
+
+    FIELD = /[^#{Fingerprint::GO_SPACE[1..-2]}]+/o
+    TRAILING_PUNCT = /[.,;:!?)"']+\z/
+    CODE_CHARS = /[:#\/()_=<>@\[\]{}"']/
+
+    class << self
+      # internal/scrub.Text: every shape rule, in order.
+      def text(line)
+        RULES.reduce(utf8(line)) { |out, (re, with)| out.gsub(re, with) }
+      end
+
+      # internal/scrub.Prose: runs of two or more capitalised words that are
+      # not framework vocabulary become <redacted:name>.
+      def prose(line)
+        return line if line.empty?
+
+        fields = line.scan(FIELD)
+        return line if fields.length < 2
+
+        out = []
+        run = []
+        flush = lambda do
+          if run.length >= 2
+            out << '<redacted:name>'
+          elsif run.length == 1
+            out << run.first
+          end
+          run.clear
+        end
+
+        fields.each do |field|
+          if proper_noun?(field)
+            run << field
+          else
+            flush.call
+            out << field
+          end
+        end
+        flush.call
+        out.join(' ')
+      end
+
+      # The sidecar's forEgress in strict mode, for one line: any trace kept
+      # as is, the rest templated, scrubbed and prose-masked.
+      def egress(line)
+        line = utf8(line)
+        match = TRACE.match(line)
+        body = match ? line.gsub(TRACE, '<trace>') : line
+        redacted = strict(body)
+        match ? "[#{match[0]}] #{redacted}" : redacted
+      end
+
+      # A bundle's template text: as the sidecar's answerEvidenceRequests
+      # does, strict redaction and then a second shape pass.
+      def template_text(text)
+        self.text(strict(utf8(text)))
+      end
+
+      private
+
+      def strict(body)
+        prose(text(Fingerprint.template(body)))
+      end
+
+      def proper_noun?(token)
+        trimmed = token.sub(TRAILING_PUNCT, '')
+        return false if trimmed.bytesize < 2
+        return false if CODE_CHARS.match?(trimmed)
+        return false if trimmed == trimmed.upcase
+
+        first = trimmed.getbyte(0)
+        return false if first < 65 || first > 90 # 'A'..'Z'
+        return false if trimmed.match?(/[0-9]/)
+
+        !VOCABULARY.key?(trimmed.downcase)
+      end
+
+      def utf8(text)
+        text = text.to_s
+        return text if text.encoding == Encoding::UTF_8 && text.valid_encoding?
+
+        text.encode('UTF-8', invalid: :replace, undef: :replace).scrub
+      end
+    end
+  end
+end

data/lib/devbench/session.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+
+module Devbench
+  # Session tokens prove a browser was served by the customer's real backend.
+  #
+  # The ingest key is public — it ships in a JavaScript bundle, so anyone can
+  # read it and post with it. A session token closes that gap without the
+  # customer writing anything: the Rack middleware they already install for
+  # trace propagation mints one and injects it into HTML responses.
+  #
+  # This must agree byte for byte with the Go SDK, because a token minted by a
+  # Rails app is verified by ingest. Divergence produces a request that succeeds
+  # locally and is rejected in production, with nothing to say why —
+  # testdata/session_vectors.json is what holds the two together.
+  module Session
+    HEADER = 'x-adt-session'
+    META_NAME = 'adt-session'
+    PREFIX = 'adts1'
+
+    # Deliberately long: the token asserts only "served by the real app", so a
+    # long life costs little, and a single-page application does full page loads
+    # rarely — a short TTL would expire mid-session and force a refresh endpoint,
+    # which is more surface in the customer's app for no security gain.
+    DEFAULT_TTL = 3600
+    MAX_SUBJECT = 128
+
+    class Expired < StandardError; end
+    class Invalid < StandardError; end
+
+    Token = Struct.new(:tenant, :subject, :expires)
+
+    # Mints a token. subject is optional — pass a stable user identifier for
+    # per-user attribution, or leave it nil.
+    def self.mint(secret, tenant, subject: nil, ttl: DEFAULT_TTL)
+      raise ArgumentError, 'secret is required' if secret.nil? || secret.strip.empty?
+      raise ArgumentError, 'tenant is required' if tenant.nil? || tenant.strip.empty?
+
+      subject = subject.to_s[0, MAX_SUBJECT]
+      ttl = DEFAULT_TTL if ttl.nil? || ttl <= 0
+
+      # The payload is pipe-delimited, so a pipe in a field would let a crafted
+      # subject forge a different tenant.
+      if tenant.include?('|') || subject.include?('|')
+        raise ArgumentError, "tenant and subject must not contain '|'"
+      end
+
+      payload = "#{tenant}|#{Time.now.to_i + ttl}|#{subject}"
+      encoded = b64(payload)
+
+      "#{PREFIX}.#{encoded}.#{sign(secret, encoded)}"
+    end
+
+    # Verifies a token, returning a Token or raising Invalid/Expired.
+    def self.verify(secret, token)
+      raise Invalid if secret.nil? || secret.strip.empty?
+      raise Invalid unless token.is_a?(String)
+
+      parts = token.strip.split('.')
+      raise Invalid unless parts.length == 3 && parts[0] == PREFIX
+
+      # Constant time: a signature check that leaks timing can be brute-forced
+      # a byte at a time.
+      raise Invalid unless OpenSSL.secure_compare(parts[2], sign(secret, parts[1]))
+
+      raw = unb64(parts[1])
+      raise Invalid if raw.nil?
+
+      fields = raw.split('|', 3)
+      raise Invalid unless fields.length == 3
+
+      expires = Integer(fields[1], exception: false)
+      raise Invalid if expires.nil?
+
+      # Expiry is checked after the signature, so an unsigned token can never
+      # reveal whether a guessed expiry was plausible.
+      raise Expired if Time.now.to_i > expires
+
+      Token.new(fields[0], fields[2], Time.at(expires))
+    end
+
+    def self.sign(secret, encoded_payload)
+      b64(OpenSSL::HMAC.digest('SHA256', secret, encoded_payload))
+    end
+
+    # Base64url without padding, matching Go's RawURLEncoding.
+    def self.b64(bytes)
+      Base64.urlsafe_encode64(bytes, padding: false)
+    end
+
+    def self.unb64(text)
+      Base64.urlsafe_decode64(text)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/devbench/session_middleware.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'session'
+
+module Devbench
+  # Rack middleware that injects a session token into HTML responses.
+  #
+  # Automatic on purpose. The customer already installs Devbench::Middleware for
+  # trace propagation; making them also thread a token through every layout
+  # would be real work in their codebase for something that can be done here.
+  #
+  #   config.middleware.insert_before 0, Devbench::SessionMiddleware,
+  #     secret: ENV['ADT_SESSION_SECRET'], tenant: 'acme'
+  #
+  # Only HTML responses are touched. JSON, images, and downloads pass through.
+  class SessionMiddleware
+    def initialize(app, secret:, tenant:, ttl: Session::DEFAULT_TTL, subject: nil)
+      @app = app
+      @secret = secret
+      @tenant = tenant
+      @ttl = ttl
+      @subject = subject
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      return [status, headers, body] if @secret.to_s.empty? || @tenant.to_s.empty?
+      return [status, headers, body] unless html?(headers)
+
+      token = begin
+        Session.mint(@secret, @tenant, subject: @subject&.call(env), ttl: @ttl)
+      rescue StandardError
+        # Never fail a page over instrumentation.
+        return [status, headers, body]
+      end
+
+      rendered = +''
+      body.each { |chunk| rendered << chunk }
+      body.close if body.respond_to?(:close)
+
+      injected = inject(rendered, token)
+
+      # A stale Content-Length truncates the page in the browser.
+      headers = headers.dup
+      headers.delete('Content-Length')
+      headers.delete('content-length')
+      headers['Content-Length'] = injected.bytesize.to_s
+
+      [status, headers, [injected]]
+    end
+
+    private
+
+    def html?(headers)
+      value = headers.find { |k, _| k.to_s.downcase == 'content-type' }&.last
+      value.to_s.downcase.include?('text/html')
+    end
+
+    def inject(document, token)
+      tag = %(<meta name="#{Session::META_NAME}" content="#{escape(token)}">)
+
+      idx = document =~ /<head[^>]*>/i
+      return document if idx.nil?
+
+      insert_at = idx + Regexp.last_match(0).length
+      document[0...insert_at] + tag + document[insert_at..]
+    end
+
+    def escape(text)
+      text.gsub('&', '&amp;').gsub('"', '&quot;').gsub('<', '&lt;').gsub('>', '&gt;')
+    end
+  end
+end

data/lib/devbench/sidecar_transport.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'socket'
+
+module Devbench
+  # Sidecar mode: each report is one line of JSON on the local sidecar's
+  # unix socket (docs/SERVER_SDK_SPEC.md, "Control socket — v1"). Used when no
+  # DSN is set; unchanged from 0.4.
+  #
+  # Never blocks for long: this runs inside rescue blocks and exception
+  # paths in the customer's request, and a diagnostics call that can hang
+  # there would turn a failure into an outage.
+  module SidecarTransport
+    MAX_LINE = 256 * 1024
+
+    # The longest a report may hold up the request that produced it. A
+    # sidecar that has stopped reading costs this much, once per report, and
+    # never more.
+    WRITE_TIMEOUT = 0.2
+
+    class << self
+      # Connects, writes one line, closes, with a deadline on both. A plain
+      # blocking write would hang the request whenever the payload outgrows
+      # the socket buffer (8 KiB on macOS) and the sidecar is not reading.
+      def deliver(payload)
+        line = "#{JSON.generate(payload)}\n"
+        return if line.bytesize > MAX_LINE
+
+        socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_STREAM)
+        begin
+          write(socket, line)
+        ensure
+          socket.close
+        end
+        nil
+      rescue StandardError, SystemStackError
+        # No sidecar, a full socket buffer, a malformed payload — none of it is
+        # the application's problem. Losing a report is always preferable to
+        # affecting the request that produced it.
+        nil
+      end
+
+      # Nothing is buffered here; the sidecar flushes on its own schedule.
+      def flush!(**)
+        true
+      end
+
+      private
+
+      def write(socket, line)
+        deadline = now + WRITE_TIMEOUT
+        address = Socket.sockaddr_un(Reporter.socket_path)
+        if socket.connect_nonblock(address, exception: false) == :wait_writable
+          return unless writable?(socket, deadline)
+
+          begin
+            socket.connect_nonblock(address)
+          rescue Errno::EISCONN
+            nil
+          end
+        end
+
+        until line.empty?
+          written = socket.write_nonblock(line, exception: false)
+          if written == :wait_writable
+            return unless writable?(socket, deadline)
+          else
+            line = line.byteslice(written..)
+          end
+        end
+      end
+
+      def writable?(socket, deadline)
+        remaining = deadline - now
+        remaining.positive? && !IO.select(nil, [socket], nil, remaining).nil?
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+
+  # Reporting is off: DEVBENCH_ENABLED=false, or a DSN that does not parse.
+  module NullTransport
+    def self.deliver(_payload)
+      nil
+    end
+
+    def self.flush!(**)
+      true
+    end
+  end
+end

data/lib/devbench/sidekiq_hooks.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative 'trace'
+require_relative 'current'
+require_relative 'reporter'
+
+module Devbench
+  # Native Sidekiq jobs (docs/SERVER_SDK_SPEC.md, Capability 2, `job`).
+  #
+  # A class that includes Sidekiq::Job never touches ActiveJob, so the
+  # perform.active_job hook sees none of its failures. This is the
+  # sentry-sidekiq equivalent:
+  #
+  #   * ServerMiddleware — outermost in the server chain. Scopes the trace and
+  #     identity to the job, reports what escapes #perform (or any middleware
+  #     inside it), then re-raises the same object, so Sidekiq's retry logic
+  #     sees exactly what it would have without it.
+  #   * ClientMiddleware — copies the active trace into the job hash at
+  #     enqueue, so a job's failure joins the request that enqueued it.
+  #   * ERROR_HANDLER — Sidekiq's error_handlers also receive failures that
+  #     never ran inside the middleware: fetch/Redis errors, a job class that
+  #     will not constantize, a failing death handler. Job failures the
+  #     middleware already sent reach it too, and are deduped by the
+  #     Reporter's mark on the exception object.
+  #
+  # Plain Ruby: no Sidekiq constant is named at load time, so this file loads
+  # without Sidekiq. Devbench::Railtie installs it at boot when Sidekiq is loaded;
+  # a non-Rails Sidekiq process calls Devbench::SidekiqHooks.install itself.
+  #
+  # Every entry point runs inside Sidekiq's processor. Anything raised from
+  # here would fail, or worse un-acknowledge, a customer's job, so each one is
+  # fully guarded — and the job's own exception is always the one that
+  # propagates.
+  module SidekiqHooks
+    # The job-hash key the trace travels in. Sidekiq passes unknown top-level
+    # keys through untouched, including across retries.
+    TRACE_KEY = 'adt_trace'
+
+    # Exceptions whose cause chain is followed looking for a shutdown.
+    MAX_CAUSES = 10
+
+    # Wraps every job the server runs.
+    class ServerMiddleware
+      def call(_job_instance, job, _queue)
+        # Scoped even without a trace: identity set inside a job must end
+        # with it, and the next job on this thread must start with none.
+        Current.with(SidekiqHooks.trace_from(job)) do
+          yield
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # Inside the scope, so the report carries this job's trace and
+          # whatever Devbench.set_user the job did. report never raises.
+          SidekiqHooks.report(e, job)
+          raise e
+        end
+      end
+    end
+
+    # Runs on every push, in the web process and, for jobs enqueued by jobs,
+    # in the server.
+    class ClientMiddleware
+      def call(_job_class, job, _queue, _redis_pool)
+        SidekiqHooks.tag(job)
+        yield
+      end
+    end
+
+    # Three parameters, the Sidekiq 7 signature; the third is optional so a
+    # caller passing two still works.
+    ERROR_HANDLER = proc do |error, context, _config = nil|
+      SidekiqHooks.handle_error(error, context)
+    end
+
+    class << self
+      # Installs the hooks into Sidekiq's global configuration. Safe to call
+      # more than once. Returns true when Sidekiq is loaded and the hooks
+      # were registered with it.
+      #
+      # configure_server blocks run only in the Sidekiq process (and for
+      # embedded Sidekiq), configure_client blocks only outside it.
+      def install
+        return false unless defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+
+        ::Sidekiq.configure_server do |config|
+          install_server(config)
+          install_client(config)
+        end
+        ::Sidekiq.configure_client { |config| install_client(config) }
+        true
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # The server middleware, outermost so a failure in another middleware
+      # is seen too, and the error handler. Returns true when installed.
+      def install_server(config)
+        config.server_middleware do |chain|
+          # prepend replaces an existing entry for the class, so this is
+          # idempotent.
+          chain.respond_to?(:prepend) ? chain.prepend(ServerMiddleware) : chain.add(ServerMiddleware)
+        end
+
+        handlers = config.error_handlers
+        handlers << ERROR_HANDLER unless handlers.any? { |h| h.equal?(ERROR_HANDLER) }
+        true
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      def install_client(config)
+        config.client_middleware { |chain| chain.add(ClientMiddleware) }
+        true
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # Called from the server middleware's rescue.
+      def report(error, job)
+        return nil if control_flow?(error)
+
+        Reporter.capture(error, context: 'job', handled: false, symbol: job_symbol(job))
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+
+      # Called by Sidekiq's handle_exception. A job failure the middleware
+      # sent is already marked and is skipped by Reporter.capture.
+      def handle_error(error, context)
+        return nil if control_flow?(error)
+
+        job = context.is_a?(Hash) ? context[:job] : nil
+        symbol = job.is_a?(Hash) ? job_symbol(job) : sidekiq_symbol(context)
+
+        # Outside any job scope: the job's own trace if there is one, and
+        # never the identity of whatever this thread last held.
+        Current.with(trace_from(job)) do
+          Reporter.capture(error, context: 'job', handled: false, symbol: symbol)
+        end
+        nil
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+
+      # Copies the active trace into a job hash being enqueued. Never
+      # replaces one already there: a re-push (a retry, an interrupted
+      # iterable job) keeps the request it came from.
+      def tag(job)
+        return nil unless job.is_a?(Hash) && !job.key?(TRACE_KEY)
+
+        trace = Current.trace
+        job[TRACE_KEY] = trace.to_s unless trace.nil?
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      def trace_from(job)
+        return nil unless job.is_a?(Hash)
+
+        Trace.parse(job[TRACE_KEY])
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Sidekiq's own control flow, never an application failure:
+      # Sidekiq::Shutdown is already skipped as a SignalException; the
+      # JobRetry::Handled/Skip and Job::Interrupted it raises through the
+      # middleware are on Reporter::NEVER_REPORTED. What remains is an
+      # exception *caused* by a hard shutdown — Sidekiq itself treats that
+      # as a shutdown and re-queues the job (JobRetry#exception_caused_by_shutdown?).
+      def control_flow?(error)
+        cause = error
+        MAX_CAUSES.times do
+          return false if cause.nil?
+          return true if cause.class.ancestors.any? { |mod| mod.name == 'Sidekiq::Shutdown' }
+
+          cause = cause.cause
+        end
+        false
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # "InvoiceSyncJob#perform". An ActiveJob run through Sidekiq's adapter
+      # arrives as a JobWrapper with the real class in "wrapped".
+      def job_symbol(job)
+        return nil unless job.is_a?(Hash)
+
+        name = job['wrapped'] || job['class']
+        name = name.name if name.is_a?(Module)
+        return nil unless name.is_a?(String) && !name.empty?
+
+        "#{name}#perform"
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      private
+
+      # Sidekiq's description of where it caught an error outside a job
+      # ("Error calling death handler"), or just "Sidekiq" (a fetch error
+      # carries none).
+      def sidekiq_symbol(context)
+        label = context.is_a?(Hash) ? context[:context] : nil
+        label.is_a?(String) && !label.empty? ? "Sidekiq: #{label}" : 'Sidekiq'
+      end
+    end
+  end
+end