restless-sdk 0.1.0

data/lib/restless/redact.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "json"
+require "set"
+
+require_relative "text"
+
+module Restless
+  # CONTRACT.md section 4. Redaction for sensitive values in captured
+  # requests. Runs at the single choke point before anything enters the
+  # upload queue; no adapter may bypass it.
+  #
+  # Format: `<REDACTED:<length>[:<last4>]>`
+  module Redact
+    TAIL_MIN_LENGTH = 8
+    TAIL_CHARS = 4
+
+    # REDACT-011. Matched after REDACT-010 normalization.
+    DEFAULT_HEADER_DENYLIST = %w[
+      authorization
+      cookie
+      set-cookie
+      proxy-authorization
+      x-api-key
+      x-auth-token
+    ].freeze
+
+    # REDACT-012.
+    DEFAULT_BODY_KEY_DENYLIST = %w[
+      password
+      pass
+      pwd
+      token
+      secret
+      apikey
+      accesstoken
+      refreshtoken
+      idtoken
+      sessionid
+      ssn
+      creditcard
+      ccnumber
+      cvv
+      cvc
+    ].freeze
+
+    # REDACT-013. Query params use the same list as body keys.
+    DEFAULT_QUERY_PARAM_DENYLIST = DEFAULT_BODY_KEY_DENYLIST
+
+    # REDACT-016. Headers that carry an HTTP auth-scheme prefix. For these the
+    # scheme word survives, so a debugger reading the dashboard can see at a
+    # glance whether the caller used Bearer, Basic or something custom.
+    SCHEME_PREFIX_HEADERS = Set.new(%w[authorization proxyauthorization]).freeze
+
+    # REDACT-030. 256 KiB, measured in UTF-8 bytes.
+    MAX_BODY_BYTES = 262_144
+
+    # PRIM-006. Hex digits are validated explicitly rather than handed to
+    # `String#to_i(16)`, which silently returns 0 for garbage.
+    HEX_PAIR_RE = /\A[0-9a-fA-F]{2}\z/.freeze
+
+    # REDACT-028. The RFC 3986 unreserved set, spelled out. No two languages'
+    # builtins agree: `encodeURIComponent` also leaves `!'()*` alone, Ruby's
+    # `CGI.escape` turns a space into `+` and escapes `~`, and Go's differs
+    # from both.
+    UNRESERVED_BYTES = begin
+      set = Array.new(256, false)
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
+        .each_byte { |b| set[b] = true }
+      set.freeze
+    end
+
+    module_function
+
+    # REDACT-001, REDACT-002. Length and tail are counted in CODE POINTS.
+    #
+    # An emoji is 1 code point, 2 UTF-16 code units and 4 UTF-8 bytes; a
+    # sentinel built from any other unit disagrees with every other SDK for
+    # the same secret, and a byte-wise tail slice produces an ill-formed
+    # string.
+    def redact_value(value)
+      points = value.chars
+      len = points.length
+      return "<REDACTED:#{len}>" if len < TAIL_MIN_LENGTH
+
+      "<REDACTED:#{len}:#{points.last(TAIL_CHARS).join}>"
+    end
+
+    # REDACT-010. Lowercase (PRIM-020, FULL Unicode) and drop every `-` and
+    # `_`, so `api_key`, `apiKey`, `API-KEY` and `APIKEY` all match `apikey`.
+    #
+    # Full Unicode, and that is a SECURITY requirement rather than a cosmetic
+    # one. This function is what decides whether a value gets redacted, so the
+    # safe direction is to fold MORE aggressively, never less. A header named
+    # `x-api-Key` or a body key `toKen` whose `K` is U+212A KELVIN SIGN
+    # full-lowercases to `x-api-key` / `token` -- both denylisted -- and the
+    # reference redacts them.
+    #
+    # An ASCII-only fold leaves the KELVIN spelling unmatched and ships the
+    # plaintext secret to the dashboard. Do not reintroduce it, and do not
+    # substitute `casefold`-style folding either (PRIM-020).
+    def normalize_name(name)
+      Text.full_lower(name).delete("-_")
+    end
+
+    def build_deny_set(defaults, extra)
+      # REDACT-014: defaults are ALWAYS applied. Configuration extends the
+      # lists; it can never shrink or replace them.
+      Set.new((defaults + Array(extra)).map { |n| normalize_name(n.to_s) })
+    end
+
+    # REDACT-016. Split `Bearer <credential>` into its three parts, or nil
+    # when there is no scheme prefix to preserve.
+    #
+    # An explicit scan over CODE POINTS, never a regex. The obvious pattern
+    # `^(\S+)(\s+)(\S.*)$` is unportable and fails silently: JavaScript's `.`
+    # excludes CR/LS/PS so a credential containing a stray CR falls through to
+    # whole-value redaction, while a Ruby or Python `.` with DOTALL matches
+    # and preserves the scheme. Same header, same input, two captured values.
+    def split_auth_scheme(value)
+      chars = value.chars
+      i = 0
+      i += 1 while i < chars.length && !Text.ws?(chars[i])
+      # No whitespace at all, or the value starts with it: nothing to keep.
+      return nil if i.zero? || i >= chars.length
+
+      j = i
+      j += 1 while j < chars.length && Text.ws?(chars[j])
+      return nil if j >= chars.length # whitespace but no credential after it
+
+      {
+        scheme: chars[0, i].join,
+        gap: chars[i, j - i].join,
+        credential: chars[j..-1].join
+      }
+    end
+
+    # REDACT-018, REDACT-019. Returns a NEW hash; never mutates the caller's.
+    def redact_headers(headers, extra = [])
+      deny = build_deny_set(DEFAULT_HEADER_DENYLIST, extra)
+      out = {}
+      headers.each do |key, value|
+        norm = normalize_name(key.to_s)
+        unless deny.include?(norm)
+          out[key] = value
+          next
+        end
+
+        if SCHEME_PREFIX_HEADERS.include?(norm)
+          split = split_auth_scheme(value.to_s)
+          if split
+            out[key] = "#{split[:scheme]}#{split[:gap]}" \
+                       "#{redact_value(split[:credential])}"
+            next
+          end
+        end
+
+        out[key] = redact_value(value.to_s)
+      end
+      out
+    end
+
+    # REDACT-028.
+    def percent_encode(value)
+      out = +""
+      Text.to_utf8(value).each_byte do |b|
+        out << (UNRESERVED_BYTES[b] ? b.chr : format("%%%02X", b))
+      end
+      out
+    end
+
+    # REDACT-029. `+` is a space, `%XX` is a byte, a `%` not followed by two
+    # hex digits is literal, and invalid UTF-8 in the decoded bytes becomes
+    # U+FFFD instead of raising.
+    #
+    # Iterates CODE POINTS. Node's original indexed UTF-16 code units, walked
+    # into the middle of an astral character and handed each surrogate half to
+    # the encoder separately, turning one emoji into two U+FFFD -- so the
+    # sentinel reported the wrong length.
+    def percent_decode(value)
+      bytes = []
+      chars = value.chars
+      i = 0
+      len = chars.length
+      while i < len
+        ch = chars[i]
+        if ch == "+"
+          bytes << 0x20
+          i += 1
+          next
+        end
+        if ch == "%"
+          pair = chars[i + 1, 2]
+          if pair && pair.length == 2
+            hex = pair.join
+            if HEX_PAIR_RE.match?(hex)
+              bytes << hex.to_i(16)
+              i += 3
+              next
+            end
+          end
+        end
+        Text.to_utf8(ch).each_byte { |b| bytes << b }
+        i += 1
+      end
+      Text.bytes_to_utf8(bytes)
+    end
+
+    # REDACT-025..027. Rewrite denylisted query values IN PLACE.
+    #
+    # Scheme, host, port, path, parameter order, separators and fragment come
+    # through byte for byte; only the matched values change. Parsing and
+    # re-serializing through a URL library is wrong twice over: it loses
+    # repeated parameters (`?token=a&token=b` collapses to one) and it applies
+    # WHATWG normalization no other language reproduces.
+    def redact_url(url, extra = [])
+      deny = build_deny_set(DEFAULT_QUERY_PARAM_DENYLIST, extra)
+
+      q = url.index("?")
+      return url if q.nil?
+
+      head = url[0, q + 1]
+      rest = url[(q + 1)..-1] || ""
+
+      hash = rest.index("#")
+      query = hash.nil? ? rest : rest[0, hash]
+      tail  = hash.nil? ? "" : rest[hash..-1]
+      return url if query.empty?
+
+      # `split("&", -1)`: without the negative limit Ruby drops trailing empty
+      # fields, so `?a=1&` would come back as `?a=1`.
+      parts = query.split("&", -1).map do |pair|
+        eq = pair.index("=")
+        next pair if eq.nil?
+
+        raw_key = pair[0, eq]
+        raw_val = pair[(eq + 1)..-1] || ""
+        next pair unless deny.include?(normalize_name(percent_decode(raw_key)))
+
+        "#{raw_key}=#{percent_encode(redact_value(percent_decode(raw_val)))}"
+      end
+
+      head + parts.join("&") + tail
+    end
+
+    # REDACT-022. Recursively redact denylisted keys in a parsed JSON value.
+    def redact_json_value(val, deny)
+      return val if val.nil?
+      return val.map { |v| redact_json_value(v, deny) } if val.is_a?(Array)
+
+      if val.is_a?(Hash)
+        out = {}
+        val.each do |k, v|
+          if deny.include?(normalize_name(k.to_s))
+            # REDACT-004: a non-string value becomes the bare `<REDACTED>`;
+            # null is left alone (there is nothing to leak, and nulling it out
+            # would lose schema information).
+            out[k] = if v.nil?
+                       nil
+                     elsif v.is_a?(String)
+                       redact_value(v)
+                     else
+                       "<REDACTED>"
+                     end
+          else
+            out[k] = redact_json_value(v, deny)
+          end
+        end
+        return out
+      end
+
+      val
+    end
+
+    # REDACT-021. Walk the PARSED value rather than pattern-matching the raw
+    # text, so every SDK reaches the same verdict with its own JSON parser and
+    # there is no regex dialect or escape decoding to get wrong.
+    def contains_denied_key?(val, deny)
+      return false if val.nil?
+      return val.any? { |v| contains_denied_key?(v, deny) } if val.is_a?(Array)
+
+      if val.is_a?(Hash)
+        val.each do |k, v|
+          return true if deny.include?(normalize_name(k.to_s))
+          return true if contains_denied_key?(v, deny)
+        end
+      end
+
+      false
+    end
+
+    # REDACT-020..024.
+    #
+    # When the body contains NOTHING to redact, the caller's original string
+    # is returned BYTE FOR BYTE rather than a re-serialized copy. That is a
+    # fidelity requirement, not an optimization: a parse/serialize round trip
+    # is lossy in every language, differently, and re-serialization is exactly
+    # where SDKs disagree.
+    def redact_body(body, content_type, extra = [])
+      return body if body.nil? || body.empty?
+      # REDACT-023: case-insensitive substring match on the content type.
+      return body unless Text.full_lower(content_type.to_s).include?("application/json")
+
+      begin
+        # max_nesting: false because the reference parser has no depth limit;
+        # a 200-deep body must not silently take a different branch here.
+        parsed = JSON.parse(body, max_nesting: false)
+      rescue StandardError
+        # REDACT-024: a body that does not parse passes through unchanged.
+        return body
+      end
+
+      deny = build_deny_set(DEFAULT_BODY_KEY_DENYLIST, extra)
+      return body unless contains_denied_key?(parsed, deny)
+
+      # PRIM-030 (compact), PRIM-031 (insertion order), PRIM-032 (literal
+      # UTF-8). Ruby's JSON encoder does all three by default.
+      JSON.generate(redact_json_value(parsed, deny))
+    rescue StandardError
+      body
+    end
+
+    # REDACT-030..032. The cut is made at the byte limit and then backed off
+    # to the nearest character boundary, so the kept prefix is always a
+    # complete sequence of Unicode scalar values.
+    def truncate_body(body, max_bytes)
+      return body if body.nil? || body.empty?
+
+      buf = Text.to_utf8(body).dup.force_encoding(Encoding::ASCII_8BIT)
+      total = buf.bytesize
+      return body if total <= max_bytes
+
+      cut = max_bytes
+      cut = 0 if cut.negative?
+      # Walk back off any UTF-8 continuation byte (0b10xxxxxx).
+      cut -= 1 while cut.positive? && (buf.getbyte(cut) & 0xC0) == 0x80
+
+      kept = buf.byteslice(0, cut).force_encoding(Encoding::UTF_8)
+      "#{kept}\n[...TRUNCATED: original #{total} bytes]"
+    end
+  end
+end

data/lib/restless/request_id.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Restless
+  # CONTRACT.md section 6.
+  module RequestId
+    UUID_RE = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/.freeze
+
+    # REQID-005. `/m` so `.` behaves like a JavaScript `.` cannot -- it is a
+    # superset, and the UUID test below is strict enough that the extra
+    # matches are all rejected anyway, which makes the two engines agree.
+    PREFIXED_RE = /\A[A-Za-z0-9]{1,7}-(.+)\z/m.freeze
+
+    module_function
+
+    # REQID-001, REQID-002. An RFC 4122 v4 UUID from a CSPRNG, lowercase and
+    # hyphenated. Explicitly NOT time-ordered: request ids appear in
+    # user-visible URLs and logs and must not leak ordering or timing.
+    def new_request_id
+      SecureRandom.uuid
+    end
+
+    # REQID-004. A configured prefix is for DISPLAY only; the raw UUID is what
+    # goes on the wire as `_id` (WIRE-011).
+    def format_request_id(raw_id, prefix = nil)
+      return raw_id if prefix.nil? || prefix.empty?
+
+      "#{prefix}-#{raw_id}"
+    end
+
+    # REQID-005. Returns group 1 only when it is itself a valid UUID;
+    # otherwise the input comes back untouched.
+    def strip_request_id_prefix(request_id)
+      match = PREFIXED_RE.match(request_id)
+      return request_id unless match
+      return match[1] if UUID_RE.match?(match[1])
+
+      request_id
+    end
+
+    def valid_request_id?(raw)
+      UUID_RE.match?(strip_request_id_prefix(raw))
+    end
+
+    # REQID-010, REQID-011. Exactly one id header per response.
+    #
+    # Emit `x-request-id` -- the header everyone knows -- carrying our freshly
+    # minted id. If the incoming request already carried one (a client, a
+    # reverse proxy, upstream middleware), fall back to `x-restless-id` so an
+    # existing chain is never clobbered.
+    #
+    # The literal `missing-key` is the setup CLI's signal that the server is
+    # running but the key never loaded, as opposed to the request silently
+    # dropping before upload.
+    def response_headers(our_id, incoming_headers, prefix = nil, has_api_key = true)
+      value = has_api_key ? format_request_id(our_id, prefix) : "missing-key"
+      incoming = incoming_headers["x-request-id"]
+      name = incoming.nil? || incoming == "" || incoming == false ? "x-request-id" : "x-restless-id"
+      { name => value }
+    end
+  end
+end

data/lib/restless/settings.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Restless
+  # CONTRACT.md section 12. `.restless/settings.json` is created and owned by
+  # the `api` CLI (`npx api setup`); the SDK consumes exactly two fields of it
+  # at runtime (CONFIG-015).
+  module Settings
+    class ConfigError < StandardError; end
+
+    @cache = nil
+    @loaded = false
+    @mutex = Mutex.new
+
+    class << self
+      # CONFIG-010, CONFIG-011. Walk up from the working directory to the
+      # filesystem root, take the first hit, and read at most once per process
+      # -- including the negative result.
+      def load(start_dir = Dir.pwd)
+        @mutex.synchronize do
+          return @cache if @loaded
+
+          @loaded = true
+          @cache = read_settings(start_dir)
+        end
+      end
+
+      # Test-only. Do not call from production code.
+      def reset_cache!
+        @mutex.synchronize do
+          @loaded = false
+          @cache = nil
+        end
+      end
+
+      # CONFIG-013, CONFIG-014. Returns {id:, name:, request_id_prefix:,
+      # redact:} or nil.
+      def resolve_api(settings, name = nil)
+        return nil if settings.nil?
+
+        apis = settings["apis"]
+        return nil unless apis.is_a?(Array) && !apis.empty?
+
+        if name && !name.empty?
+          match = apis.find { |a| a["name"] == name } || apis.find { |a| a["id"] == name }
+          unless match
+            raise ConfigError,
+                  "restless-sdk: no API named #{name.inspect} in .restless/settings.json " \
+                  "(found: #{apis.map { |a| a['name'] }.join(', ')})"
+          end
+          return entry(match)
+        end
+
+        return entry(apis[0]) if apis.length == 1
+
+        # Guessing would silently apply the wrong redaction list.
+        raise ConfigError,
+              "restless-sdk: .restless/settings.json has multiple APIs " \
+              "(#{apis.map { |a| a['name'] }.join(', ')}) -- pass api: \"<name>\" to " \
+              "Restless::Client.new to pick one."
+      end
+
+      private
+
+      def entry(api)
+        {
+          id: api["id"],
+          name: api["name"],
+          request_id_prefix: api["requestIdPrefix"],
+          redact: api["redact"].is_a?(Hash) ? api["redact"] : nil
+        }
+      end
+
+      def read_settings(start_dir)
+        file = find_settings_file(start_dir)
+        return nil if file.nil?
+
+        # CONFIG-012: a missing or malformed file yields no configuration. It
+        # must not raise and must not prevent construction.
+        parsed = JSON.parse(File.read(file))
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue StandardError
+        nil
+      end
+
+      def find_settings_file(start_dir)
+        dir = File.expand_path(start_dir)
+        loop do
+          candidate = File.join(dir, ".restless", "settings.json")
+          return candidate if File.file?(candidate)
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+    end
+  end
+end

data/lib/restless/stack_frames.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+require_relative "fingerprint"
+
+module Restless
+  # CONTRACT.md FP-043, FP-044, FP-045. The Ruby dialect of stack parsing.
+  #
+  # FP-044 makes frame parsing and the skip list explicitly per-language: only
+  # the OUTPUT shape is contract surface. This module is therefore the one
+  # place in the SDK that knows what a Ruby backtrace looks like, and the
+  # shared conformance vectors deliberately do not cover it (FP-046); see
+  # `test/test_stack_frames.rb`.
+  module StackFrames
+    # Ruby <= 3.3: "path.rb:12:in `method'"
+    # Ruby >= 3.4: "path.rb:12:in 'Klass#method'"
+    FRAME_RE = /\A(.+):(\d+):in [`'](.+)'\z/.freeze
+    # Some frames carry no method label at all.
+    FRAME_NO_FN_RE = /\A(.+):(\d+)\z/.freeze
+
+    # `block (3 levels) in handler` -> `block in handler`. The nesting count
+    # is closer to a line number than to an identity: it moves when somebody
+    # wraps the throw site in one more `each`, which FP-041 says must not
+    # split a group.
+    BLOCK_LEVELS_RE = /\Ablock \(\d+ levels\) in /.freeze
+
+    # Ruby 3.4 changed backtrace method labels to carry the receiver:
+    # `detonate` became `Exploder.detonate`, and `run` became `Exploder#run`.
+    # Stripping it back off is not cosmetic. Without it the SAME crash in the
+    # SAME file fingerprints differently depending on which Ruby the service
+    # happens to run, so a routine runtime upgrade silently splits every
+    # existing 5xx group and orphans the Agent Recovery guidance attached to
+    # it. FP-041 forbids exactly that churn for line numbers; a runtime
+    # version is no different.
+    #
+    # Stripping rather than keeping, because that reproduces the label Ruby
+    # 3.3 and earlier already emit, so no stored key moves.
+    RECEIVER_RE = /\A(?:[A-Z]\w*(?:::[A-Z]\w*)*)[.#]/.freeze
+
+    # FP-044. The Ruby equivalent of `node_modules` / `node:internal` /
+    # `@restlessai/sdk`.
+    #
+    # Everything here is matched by FILE PATH, never by module or class name.
+    # A name check would also skip a customer's own `Restless`-flavoured code
+    # and, worse, would not skip this gem when it is vendored under a
+    # different constant. The SDK's own directory is resolved from `__dir__`,
+    # so it is correct however the gem was installed.
+    SDK_DIR = File.expand_path("..", __dir__).freeze
+
+    STDLIB_DIRS = [
+      RbConfig::CONFIG["rubylibdir"],
+      RbConfig::CONFIG["rubyarchdir"],
+      RbConfig::CONFIG["sitelibdir"],
+      RbConfig::CONFIG["vendorlibdir"]
+    ].compact.reject(&:empty?).map { |d| File.expand_path(d) }.freeze
+
+    GEM_DIRS = begin
+      dirs = []
+      begin
+        dirs.concat(Array(Gem.path)) if defined?(Gem)
+        dirs << Gem.dir if defined?(Gem) && Gem.respond_to?(:dir)
+      rescue StandardError
+        # Gem may not be loaded at all; the "/gems/" fallback below covers it.
+      end
+      dirs.compact.uniq.map { |d| File.expand_path(d) }.freeze
+    end
+
+    module_function
+
+    # FP-043. The frame NEAREST THE THROW SITE that is not vendor, runtime or
+    # SDK code.
+    #
+    # Ruby's `Exception#backtrace` is innermost-FIRST (index 0 is where the
+    # exception was raised), like a v8 `Error.stack` and unlike a Python
+    # traceback, so the walk goes FORWARDS. Implementing this positionally in
+    # the wrong direction returns the Rack entry point for every crash in the
+    # process, which collapses every 500 into one fingerprint group and
+    # defeats the strategy entirely. Verified empirically in
+    # `test/test_stack_frames.rb`, not assumed.
+    def top_user_frame(backtrace)
+      return nil if backtrace.nil?
+
+      Array(backtrace).each do |raw|
+        frame = parse_frame(raw.to_s)
+        next if frame.nil?
+        next if skip_path?(frame[:file])
+
+        return {
+          file: Fingerprint.project_relative(frame[:file]),
+          fn: frame[:fn]
+        }
+      end
+      nil
+    end
+
+    def parse_frame(line)
+      if (m = FRAME_RE.match(line))
+        return { file: m[1], fn: normalize_fn(m[3]) }
+      end
+      if (m = FRAME_NO_FN_RE.match(line))
+        # FP-045.
+        return { file: m[1], fn: "anonymous" }
+      end
+
+      nil
+    end
+
+    def normalize_fn(name)
+      cleaned = name.sub(BLOCK_LEVELS_RE, "block in ")
+        cleaned = strip_receiver(cleaned)
+      cleaned.empty? ? "anonymous" : cleaned
+    end
+
+      # Applied after the block normalization, and to the method portion of a
+      # `block in X` label as well as a bare one, since 3.4 qualifies both.
+      def strip_receiver(name)
+        if name.start_with?("block in ")
+          "block in " + name.sub(/\Ablock in /, "").sub(RECEIVER_RE, "")
+        else
+          name.sub(RECEIVER_RE, "")
+        end
+      end
+
+    def skip_path?(path)
+      return true if path.nil? || path.empty?
+      # Ruby 3.x synthesises frames like "<internal:kernel>:90:in `tap'".
+      return true if path.start_with?("<internal:")
+      return true if path.start_with?(SDK_DIR)
+      return true if path.include?("/gems/")
+      return true if STDLIB_DIRS.any? { |dir| path.start_with?(dir) }
+      return true if GEM_DIRS.any? { |dir| path.start_with?(dir) }
+
+      false
+    end
+
+    # Convenience for adapters: fingerprint-ready frame from an exception.
+    def from_exception(error)
+      return nil unless error.respond_to?(:backtrace)
+
+      top_user_frame(error.backtrace)
+    rescue StandardError
+      nil
+    end
+  end
+end