camada 0.1.0

data/lib/camada/guarded.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Camada
+  # The fail-open envelope: a camada bug must never 5xx the customer. Every public entry point of
+  # the SDK catches, falls back, and reports through log_rate_limited: at most one line a minute.
+  module Guarded
+    @last_log = 0.0
+    @logger = nil
+
+    class << self
+      # Where the one line a minute goes: anything responding to #call(String). Default: $stderr.
+      attr_accessor :logger
+
+      def log_rate_limited(err)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return if now - @last_log < 60
+
+        @last_log = now
+        line = "[camada] suppressed error (SDK fails open): #{describe(err)}"
+        (@logger || ->(s) { warn(s) }).call(line)
+      rescue StandardError
+        nil # even logging must not raise
+      end
+
+      private
+
+      # Exceptions print as "Class: message" on one line — never a backtrace, and never the
+      # "(ClassName)" spelling an uncaught Ruby exception uses, so a crash grep stays quiet.
+      def describe(err)
+        err.is_a?(Exception) ? "#{err.class.name}: #{err.message}".tr("\n", " ") : err.to_s
+      end
+    end
+  end
+end

data/lib/camada/ip.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "ipparse"
+
+module Camada
+  # Client-IP resolution under the tenant's trusted-proxy config. The default is the socket peer:
+  # raw X-Forwarded-For is attacker-writable and is NEVER trusted without explicit configuration;
+  # a spoofed XFF must not reach the analysis or the blocklist. Ported from @camada/core src/ip.ts.
+  module Ip
+    Cidr = Struct.new(:base4, :base6, :bits) # base4: v4 base or -1; base6: words or nil
+
+    def self.valid_ip?(s)
+      s.include?(":") ? !IpParse.parse_ip6(s).nil? : IpParse.parse_ip4(s) >= 0
+    end
+
+    def self.parse_cidr(c)
+      slash = c.index("/")
+      return nil if slash.nil?
+
+      addr = c[0, slash]
+      bits = Integer(c[(slash + 1)..], 10, exception: false)
+      return nil if bits.nil?
+
+      unless addr.include?(":")
+        base = IpParse.parse_ip4(addr)
+        return base >= 0 && bits.between?(0, 32) ? Cidr.new(base, nil, bits) : nil
+      end
+      words = IpParse.parse_ip6(addr)
+      words && bits.between?(0, 128) ? Cidr.new(-1, words, bits) : nil
+    end
+
+    def self.in_cidr?(ip, cidr)
+      if cidr.base6.nil?
+        n = IpParse.parse_ip4(ip)
+        return false if n < 0
+
+        bits = cidr.bits
+        mask = bits == 0 ? 0 : (0xFFFFFFFF << (32 - bits)) & 0xFFFFFFFF
+        return (n & mask) == (cidr.base4 & mask)
+      end
+      words = IpParse.parse_ip6(ip)
+      return false if words.nil?
+
+      remaining = cidr.bits
+      4.times do |k|
+        break if remaining <= 0
+
+        take = [32, remaining].min
+        mask = take == 32 ? 0xFFFFFFFF : (0xFFFFFFFF << (32 - take)) & 0xFFFFFFFF
+        return false if (words[k] & mask) != (cidr.base6[k] & mask)
+
+        remaining -= take
+      end
+      true
+    end
+
+    # The client IP from the socket peer and X-Forwarded-For per the trusted-proxy config.
+    # Anything unresolvable falls back to the peer (fail safe).
+    def self.resolve_client_ip(peer, xff, cfg)
+      sock = peer&.start_with?("::ffff:") ? peer[7..] : peer # dual-stack v4-mapped form
+      return sock if cfg.nil? || cfg["mode"] == "none" || xff.nil? || xff.empty?
+
+      entries = xff.split(",").map(&:strip).reject(&:empty?)
+      return sock if entries.empty?
+
+      candidate = nil
+      case cfg["mode"]
+      when "hops"
+        hops = cfg["hops"].to_i
+        candidate = entries[entries.length - hops] if hops.between?(1, entries.length)
+      when "vercel"
+        candidate = entries.last # Vercel overwrites XFF, so its rightmost entry is trustworthy
+      when "cidrs"
+        trusted = (cfg["cidrs"] || []).filter_map { |x| parse_cidr(x.to_s) }
+        candidate = entries.reverse_each.find { |entry| trusted.none? { |t| in_cidr?(entry, t) } }
+      end
+      candidate && valid_ip?(candidate) ? candidate : sock
+    end
+  end
+end

data/lib/camada/ipparse.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Camada
+  # Allocation-free IP parsers, ported 1:1 from edge-analyst src/blocklist.js through
+  # @camada/core src/snapshot/ipparse.ts (the reference the conformance fixtures are generated
+  # from). Behaviour must not drift: ip4 returns -1 on anything unusual; ip6 rejects zone ids and
+  # v4-mapped forms. Ruby integers are unbounded, so the words come back as a 4-element Array
+  # instead of being written into a caller's scratch array.
+  module IpParse
+    DOT = 46
+    COLON = 58
+    ZERO = 48
+    NINE = 57
+
+    # Dotted-quad IPv4 to a uint32, or -1 when the string is not a plain IPv4 address.
+    def self.parse_ip4(s)
+      n = part = digits = dots = 0
+      s.each_byte do |ch|
+        if ch == DOT
+          return -1 if digits == 0 || part > 255
+
+          dots += 1
+          return -1 if dots > 3
+
+          n = (n * 256) + part
+          part = digits = 0
+        elsif ch.between?(ZERO, NINE)
+          part = (part * 10) + (ch - ZERO)
+          digits += 1
+          return -1 if digits > 3
+        else
+          return -1
+        end
+      end
+      return -1 if dots != 3 || digits == 0 || part > 255
+
+      (n * 256) + part
+    end
+
+    # IPv6 text to four big-endian uint32 words, or nil when it is not a plain IPv6 address.
+    def self.parse_ip6(s)
+      length = s.bytesize
+      groups = Array.new(8, 0)
+      n = val = digits = 0
+      dbl = -1
+      i = 0
+      if length > 1 && s.getbyte(0) == COLON && s.getbyte(1) == COLON
+        dbl = 0
+        i = 2
+      end
+      while i <= length
+        c = i < length ? s.getbyte(i) : COLON # a sentinel colon closes the last group
+        if c == COLON
+          if digits > 0
+            return nil if n >= 8
+
+            groups[n] = val
+            n += 1
+            val = digits = 0
+          elsif i < length
+            return nil if dbl != -1
+
+            dbl = n
+          end
+        else
+          d = hex_digit(c)
+          return nil if d.nil?
+
+          val = (val << 4) | d
+          digits += 1
+          return nil if digits > 4
+        end
+        i += 1
+      end
+      if dbl == -1
+        return nil if n != 8
+      else
+        return nil if n >= 8
+
+        shift = 8 - n
+        7.downto(dbl + shift) { |k| groups[k] = groups[k - shift] }
+        (dbl...(dbl + shift)).each { |k| groups[k] = 0 }
+      end
+      [
+        (groups[0] << 16) | groups[1],
+        (groups[2] << 16) | groups[3],
+        (groups[4] << 16) | groups[5],
+        (groups[6] << 16) | groups[7]
+      ]
+    end
+
+    def self.hex_digit(c)
+      if c.between?(ZERO, NINE) then c - ZERO
+      elsif c.between?(97, 102) then c - 87  # a-f
+      elsif c.between?(65, 70) then c - 55   # A-F
+      end
+    end
+    private_class_method :hex_digit
+  end
+end

data/lib/camada/rack.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "body_proxy"
+require_relative "engine"
+require_relative "guarded"
+
+module Camada
+  # Rack middleware: `use Camada::Rack` in config.ru (or the Railtie for Rails). camada answers
+  # before routing (block, challenge, beacon), else runs the app and stamps x-rid and the _sfp
+  # cookie on its response, shipping the event when the server closes the body. The env keeps no
+  # wire header order, so the analyst reads no HEADER_ORDER signal from this tap. Nothing here
+  # requires "rack": the host already loaded it, and the gem stays dependency-free.
+  class Rack
+    # The peer is REMOTE_ADDR — never Rack::Request#ip, which trusts X-Forwarded-For. Every value
+    # the engine will match or ship goes through `utf8`: Puma tags env strings ASCII-8BIT, and a
+    # binary string with a high byte raises against a UTF-8 rule needle and again in
+    # JSON.generate at flush time (the whole batch, blocked rows included). WSGI hands Python
+    # str, so the reference has no such seam.
+    def self.req_from_env(env)
+      headers = []
+      env.each do |k, v|
+        if k.start_with?("HTTP_")
+          headers << [k[5..].downcase.tr("_", "-"), utf8(v)]
+        elsif (k == "CONTENT_TYPE" || k == "CONTENT_LENGTH") && v && !v.to_s.empty?
+          headers << [k.downcase.tr("_", "-"), utf8(v)]
+        end
+      end
+      query = utf8(env["QUERY_STRING"])
+      proto = env["SERVER_PROTOCOL"].to_s
+      Req.new(
+        method: (env["REQUEST_METHOD"] || "GET").to_s,
+        path: Camada.present(utf8(env["PATH_INFO"])) || "/",
+        query: query.empty? ? "" : "?#{query}",
+        host: Camada.present(utf8(env["HTTP_HOST"])) || utf8(env["SERVER_NAME"]),
+        http_version: proto.start_with?("HTTP/") ? proto[5..] : nil,
+        peer: Camada.present(utf8(env["REMOTE_ADDR"])),
+        https: env["rack.url_scheme"] == "https",
+        headers: headers
+      )
+    end
+
+    # A valid UTF-8 String for any env value: nil -> "", a binary or malformed string is read as
+    # UTF-8 with each invalid byte replaced by U+FFFD (never raises, never mutates the env's own).
+    def self.utf8(v)
+      s = v.to_s
+      return s if s.encoding == Encoding::UTF_8 && s.valid_encoding?
+
+      s.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    # At most `limit` bytes, or nil when the declared or actual size exceeds it. Whatever was
+    # read is put back so an app the request falls through to still sees its whole body (Rack 3
+    # inputs need not be rewindable, so the env gets a fresh input either way).
+    def self.read_body(env, limit)
+      declared = env["CONTENT_LENGTH"].to_i
+      return nil if declared > limit
+
+      input = env["rack.input"]
+      data = input&.read(limit + 1) || "".b
+      if data.bytesize > limit
+        env["rack.input"] = ChainedInput.new(data, input) # over the cap: the prefix, then the unread rest — lazily
+        return nil
+      end
+      env["rack.input"] = StringIO.new(data)
+      data
+    end
+
+    # The bytes camada already read, then whatever is left in the stream the app was owed (the
+    # port of wsgi.py's _Chained). Nothing past the cap is read until the app asks: a chunked
+    # POST of any size costs the process 32 KB, not the body. A Rack 3 input: gets, each, read,
+    # close — plus rewind for Rack 2 hosts, which restores the position camada left the stream at.
+    class ChainedInput
+      def initialize(head, rest)
+        @head = StringIO.new(head)
+        @rest = rest
+      end
+
+      def read(length = nil, buf = nil)
+        out = @head.read(length) || "".b
+        if length.nil?
+          out << (@rest.read || "".b)
+        elsif out.bytesize < length
+          more = @rest.read(length - out.bytesize)
+          out << more if more
+        end
+        return nil if length && length > 0 && out.empty? # IO#read: nil at EOF for a positive length
+
+        buf.nil? ? out : buf.replace(out)
+      end
+
+      def gets
+        line = @head.gets
+        return @rest.gets if line.nil?
+        return line if line.end_with?("\n")
+
+        line + (@rest.gets || "") # a line that straddles the seam
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        while (line = gets)
+          yield line
+        end
+      end
+
+      def close
+        @rest.close if @rest.respond_to?(:close)
+      end
+
+      def rewind
+        @head.rewind
+        return unless @rest.respond_to?(:rewind)
+
+        @rest.rewind
+        @rest.read(@head.string.bytesize) # back to where camada left it: the head already holds these bytes
+      end
+    end
+
+    # The matched route pattern, read at finish: Sinatra's "VERB /pattern", Rails' route_uri_pattern.
+    def self.route_of(env)
+      rails = env["action_dispatch.route_uri_pattern"]
+      return rails.to_s if rails
+
+      sinatra = env["sinatra.route"]
+      sinatra&.to_s&.sub(/\A[A-Z]+ /, "")
+    end
+
+    # `Camada::Rack.new(app)` wires the lazy default from the environment on the first request;
+    # `Camada::Rack.new(app, engine)` uses the one you built.
+    def initialize(app, engine = nil, **opts)
+      @app = app
+      @engine = engine
+      @opts = opts
+    end
+
+    def engine
+      @engine ||= Camada.default(**@opts)
+    end
+
+    def call(env)
+      eng = engine
+      begin
+        req = Rack.req_from_env(env)
+        limit = eng.wants_body(req.method, req.path)
+        body = limit.nil? ? nil : Rack.read_body(env, limit)
+      rescue StandardError => e
+        Guarded.log_rate_limited(e)
+        return @app.call(env)
+      end
+      result = eng.handle(req, body)
+      return result.to_rack if result.is_a?(Answer)
+
+      run(env, req, result)
+    end
+
+    private
+
+    def run(env, req, passed)
+      env["camada"] = passed.ctx unless passed.ctx.nil?
+      begin
+        status, headers, body = @app.call(env)
+      rescue Exception # rubocop:disable Lint/RescueException -- the server answers 500 for anything that escapes the app
+        passed.on_finish&.call(500)
+        raise
+      end
+      headers = stamp(headers, passed)
+      finish = passed.on_finish
+      return [status, headers, body] if finish.nil?
+
+      proxy = BodyProxy.new(body) do
+        req.route ||= Rack.route_of(env)
+        finish.call(status.to_i)
+      end
+      [status, headers, proxy]
+    end
+
+    # x-rid and the session cookie on the app's response. Rack 3 spells header names in lower
+    # case and carries several set-cookie values as an Array; Rack 2 joins them with "\n".
+    def stamp(headers, passed)
+      return headers if passed.rid.nil? && passed.set_cookie.nil?
+
+      headers = headers.to_h
+      headers["x-rid"] = passed.rid if passed.rid
+      if passed.set_cookie
+        key = headers.keys.find { |k| k.to_s.downcase == "set-cookie" } || "set-cookie"
+        headers[key] = join_cookies(headers[key], passed.set_cookie)
+      end
+      headers
+    rescue StandardError => e
+      Guarded.log_rate_limited(e)
+      headers
+    end
+
+    def join_cookies(existing, cookie)
+      return cookie if existing.nil? || (existing.respond_to?(:empty?) && existing.empty?)
+
+      arrays = defined?(::Rack::RELEASE) && ::Rack::RELEASE.to_s >= "3"
+      return [*existing, cookie] if existing.is_a?(Array) || arrays
+
+      "#{existing}\n#{cookie}"
+    end
+  end
+end

data/lib/camada/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "rack"
+
+# Rails: the gem inserts Camada::Rack first in the middleware stack, so camada answers before
+# anything else runs. Defined only when Rails is loaded (Bundler.require after rails); the
+# helpers are the module-level ones: Camada.script_tag(request.env), Camada.track(request.env,
+# "login_failed", user: email), Camada.serve_challenge(request.env).
+if defined?(Rails::Railtie)
+  module Camada
+    class Railtie < Rails::Railtie
+      initializer "camada.middleware" do |app|
+        app.middleware.insert_before 0, Camada::Rack
+      end
+    end
+  end
+end

data/lib/camada/redact.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Camada
+  # Redaction, non-configurable-off. The SDK never ships: Authorization/Cookie values (scheme
+  # only, events/build.rb), body field values (shape only), query params that look like
+  # credentials, or raw user identifiers (HMAC-hashed here, inside the SDK, before anything
+  # reaches the queue). Ported from @camada/core src/redact.ts.
+  module Redact
+    NAME_RE = /(pass(word)?|tok(en)?|secret|key|api[-_]?key|auth|sess(ion)?|sig(nature)?|code|jwt|bearer|credential)/i
+    JWT_RE = /\AeyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/
+    HEX_RE = /\A[a-f0-9]{32,}\z/i
+    B64_RE = %r{\A[A-Za-z0-9+/_-]{40,}={0,2}\z}
+
+    REDACT_ALLOWLIST = %w[plan role locale ab_variant].freeze # additions only, never narrowing
+
+    def self.suspect_value?(v)
+      JWT_RE.match?(v) || HEX_RE.match?(v) || B64_RE.match?(v)
+    end
+
+    # Replaces credential-looking query values with ~r, preserving structure and order.
+    def self.scrub_query(query)
+      return query || "" if query.nil? || query.length <= 1
+
+      lead = query.start_with?("?") ? "?" : ""
+      out = (lead.empty? ? query : query[1..]).split("&", -1).map do |p|
+        eq = p.index("=")
+        next p if eq.nil?
+
+        name = p[0, eq]
+        value = p[(eq + 1)..]
+        NAME_RE.match?(name) || suspect_value?(value) ? "#{name}=~r" : p
+      end
+      lead + out.join("&")
+    end
+
+    # Body shape only: field names and byte sizes, never values. One level deep.
+    def self.body_shape(obj)
+      return nil unless obj.is_a?(Hash)
+
+      obj.to_h do |k, v|
+        size = case v
+               when String then v.length
+               when nil then 0
+               else
+                 begin
+                   JSON.generate(v).length
+                 rescue StandardError
+                   0
+                 end
+               end
+        [k.to_s, size]
+      end
+    end
+
+    # Stable per-tenant pseudonym: HMAC-SHA256 keyed by the ingest token, labelled so the hash
+    # can never double as anything else, truncated to 32 hex chars. The raw identifier never leaves.
+    def self.hash_user_id(user_id, ingest_token)
+      OpenSSL::HMAC.hexdigest("SHA256", ingest_token, "uid:#{user_id}")[0, 32]
+    end
+  end
+end