camada 0.1.0

data/lib/camada/snapshot/parse.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "../constants"
+require_relative "../ipparse"
+
+module Camada
+  # BLK snapshot parser (v3, v4, v5), ported from @camada/core src/snapshot/parse.ts, itself a
+  # port of edge-analyst src/blocklist.js load() (the reference implementation).
+  #
+  # Container: sectioned little-endian uint32 —
+  #   [0] magic 0x424c4b3<version>   [1] section count K
+  #   K x [type, offset(words), length(words)]   then the sections.
+  # Types: 1 V4_STARTS  2 V4_ENDS  3 V4_IDX16  4 V4_BM24  5 V6_STARTS  6 V6_ENDS  7 V6_BM24
+  #        8 ASN_BM  9 ASN_EXTRA.
+  # v4 (contracts §A3) adds two side lists as INTERLEAVED range pairs:
+  #        10 ALLOW_V4  11 ALLOW_V6  12 CHALLENGE_V4  13 CHALLENGE_V6
+  #   *_V4: [start, end, …] (2 words per range, sorted by start)
+  #   *_V6: [s0,s1,s2,s3, e0,e1,e2,e3, …] (8 words per range, big-endian word order, sorted by start)
+  # v5 (contracts §D3) adds the tenant's ordered custom rules, which run BEFORE the three sides:
+  #        14 RULE_V4  15 RULE_V6   — repeated, word 0 = the rule's index into meta.rules, then range
+  #   pairs exactly as 10/11. One 14 + one 15 per `ip` condition, in condition order (an empty half
+  #   still ships its index word), so a rule with two ip conditions reads two pairs.
+  # Meta travels separately: { version, country[], tls[], pathsExact[], pathsPrefix[], pathsRegex[],
+  #                            allow?: side, challenge?: side, rules?: [] } with side = { asn[], country[], pathsExact[], pathsPrefix[] }.
+  # The version byte is advisory: sections 10-15 are read whenever they are present.
+  #
+  # A Uint32Array is a `Words` view: one String of bytes read a word at a time with
+  # String#unpack1("V", offset:), so a 5 MB container never becomes 1.3 M Integers, and the
+  # bitmaps are indexed, never unpacked wholesale. Ruby integers are unbounded, so every
+  # `>>> 0` of the original is simply absent.
+  module Snapshot
+    FORMATS = { 0x424C4B33 => 3, 0x424C4B34 => 4, 0x424C4B35 => 5 }.freeze
+    ACTIONS = %w[skip block challenge warn].freeze
+
+    # A read-only uint32 little-endian view over a byte String, from a byte offset, `length` words long.
+    class Words
+      attr_reader :length
+
+      def initialize(buf, byte_off = 0, length = nil)
+        @buf = buf
+        @off = byte_off
+        @length = length || [(buf.bytesize - byte_off) / 4, 0].max # a trailing partial word is dropped, as the Uint32Array view does
+      end
+
+      def [](i) = @buf.unpack1("V", offset: @off + (4 * i))
+      def slice(start, len) = Words.new(@buf, @off + (4 * start), len)
+      def empty? = @length == 0
+    end
+
+    # A zero-filled section of `length` words: what an absent bitmap/index reads as.
+    class Zeros
+      attr_reader :length
+
+      def initialize(length)
+        @length = length
+      end
+
+      def [](_i) = 0
+      def empty? = @length == 0
+    end
+
+    EMPTY = Words.new("".b, 0, 0)
+
+    # A v4 side list. `empty` short-circuits the matcher on the (common) v3 snapshot.
+    RangeSet = Struct.new(:r4, :r6, :n6, :asn, :country, :paths_exact, :paths_prefix, :empty, keyword_init: true)
+
+    # The request a compiled condition reads. `ip6` is the parsed address words, or nil; `header`
+    # is called with an already lower-cased name, absent where the tap cannot read headers.
+    RuleRequest = Struct.new(:n4, :ip6, :asn, :country, :tlsx, :path, :ua, :header, keyword_init: true)
+
+    CompiledRule = Struct.new(:id, :action, :conds)
+
+    Snap = Struct.new(
+      :version, :format, :s4, :e4, :idx4, :bm4, :s6, :e6, :n6, :bm6, :asn_bm, :asn_extra,
+      :country, :tls, :paths_exact, :paths_prefix, :paths_regex, :allow, :challenge,
+      :rules, # v5 only; empty on v3/v4, and the matcher then skips them
+      keyword_init: true
+    )
+
+    def self.range_set(r4, r6, m)
+      m ||= {}
+      asn = (m["asn"] || []).to_set(&:to_i)
+      country = (m["country"] || []).to_set
+      exact = (m["pathsExact"] || []).to_set
+      prefix = (m["pathsPrefix"] || []).to_set
+      empty = r4.empty? && r6.empty? && asn.empty? && country.empty? && exact.empty? && prefix.empty?
+      RangeSet.new(r4: r4, r6: r6, n6: r6.length >> 3, asn: asn, country: country, paths_exact: exact, paths_prefix: prefix, empty: empty)
+    end
+
+    # Binary search over interleaved [start, end] uint32 pairs sorted by start.
+    def self.in_range4?(r, n)
+      lo = 0
+      hi = (r.length >> 1) - 1
+      return false if hi < 0
+
+      while lo < hi
+        m = (lo + hi + 1) >> 1
+        if r[m * 2] <= n
+          lo = m
+        else
+          hi = m - 1
+        end
+      end
+      n.between?(r[lo * 2], r[(lo * 2) + 1])
+    end
+
+    # Compares the 4 words at a[o..o+3] against the address words.
+    def self.cmp_words(a, o, w)
+      4.times do |k|
+        x = a[o + k]
+        y = w[k]
+        return x < y ? -1 : 1 if x != y
+      end
+      0
+    end
+
+    # Binary search over an interleaved [4-word start, 4-word end] side section.
+    def self.in_range6?(r, n, w)
+      return false if n < 1
+
+      lo = 0
+      hi = n - 1
+      while lo < hi
+        m = (lo + hi + 1) >> 1
+        if cmp_words(r, m * 8, w) <= 0
+          lo = m
+        else
+          hi = m - 1
+        end
+      end
+      o = lo * 8
+      cmp_words(r, o, w) <= 0 && cmp_words(r, o + 4, w) >= 0 # rubocop:disable Style/ComparableBetween -- two different comparisons
+    end
+
+    # A pattern this runtime rejects never matches, and never throws (fail open). Patterns are
+    # authored as JS regexes (the analyst validates them with `new RegExp`), so the JS spellings
+    # Onigmo reads differently are translated first — see js_to_onigmo; \d \w \b are ASCII in
+    # Ruby by default, as JS reads them.
+    def self.compile_regex(pattern)
+      Regexp.new(js_to_onigmo(pattern))
+    rescue RegexpError, TypeError, ArgumentError, EncodingError
+      nil
+    end
+
+    # The JS-only spellings a tenant is likely to author: `[^]` (any char) -> `[\s\S]`, `\cX` ->
+    # the control character, and the anchors: JS `^`/`$` bind the whole input while Ruby's are
+    # line anchors, so outside a class they become `\A`/`\z`. `(?<name>` is native to Onigmo.
+    # Anything else Ruby rejects still fails open.
+    def self.js_to_onigmo(pattern)
+      out = +""
+      i = 0
+      n = pattern.length
+      in_class = false
+      while i < n
+        ch = pattern[i]
+        if ch == "\\" && i + 1 < n
+          if pattern[i + 1] == "c" && i + 2 < n && pattern[i + 2].match?(/[A-Za-z]/)
+            out << Regexp.escape((pattern[i + 2].upcase.ord - 64).chr)
+            i += 3
+            next
+          end
+          out << pattern[i, 2]
+          i += 2
+          next
+        end
+        if in_class
+          in_class = ch != "]"
+        elsif ch == "["
+          if pattern[i, 3] == "[^]"
+            out << "[\\s\\S]"
+            i += 3
+            next
+          end
+          in_class = true
+        elsif ch == "^"
+          out << "\\A"
+          i += 1
+          next
+        elsif ch == "$"
+          out << "\\z"
+          i += 1
+          next
+        end
+        out << ch
+        i += 1
+      end
+      out
+    end
+
+    # A regex test that never raises: a value in an encoding the pattern cannot read (a binary
+    # PATH_INFO with high bytes, say) reads as "no match" rather than an exception on the request path.
+    def self.regex_hit?(rx, value)
+      rx.match?(value)
+    rescue StandardError
+      false
+    end
+
+    # The same envelope for the plain string ops: Puma hands every env value to Rack as
+    # ASCII-8BIT while a rule's needle arrives from JSON as UTF-8, and `include?` /
+    # `start_with?` across that pair raise Encoding::CompatibilityError once either side carries a
+    # high byte. The adapter scrubs its values, but the matcher must not depend on it: an
+    # exception here escapes match(), handle() falls back to INERT and a blocked client passes.
+    def self.text_hit?
+      yield
+    rescue StandardError
+      false
+    end
+
+    # ---------- custom rules (v5) ----------
+
+    # The string one condition reads, or nil when this request cannot answer the field.
+    # `header` is not here: it needs the condition's own name, so compile_cond builds its reader.
+    def self.field_value(f, r)
+      case f
+      when "asn" then r.asn&.to_s
+      when "country" then Camada.present(r.country)
+      when "tlsx" then Camada.present(r.tlsx)
+      when "path" then r.path
+      when "ua" then Camada.present(r.ua)
+      end
+      # an entity-plane field (bot.verified, rule) answers nil: never true here
+    end
+
+    # One condition -> a predicate. `sets` yields this rule's (v4, v6) section pair per ip
+    # condition, in condition order, so an ip condition consumes the next one.
+    def self.compile_cond(c, sets)
+      f = c["f"].to_s
+      op = c["op"].to_s
+      negate = op == "is_not" || op == "not_in"
+      # A header condition reads the request through the caller's getter. The name is lower-cased
+      # once, here; a tap that cannot read headers (no getter) and a header the request does not
+      # carry are both nil, and nil is false for every op — the rule simply does not fire (fail
+      # open, §A4). The getter is app code: one that raises, or answers something other than a
+      # String, is read as "no header" rather than allowed to take the whole match() down.
+      read =
+        if f == "header"
+          hname = c["name"].to_s.downcase
+          lambda do |r|
+            next nil if hname.empty? || r.header.nil?
+
+            v = begin
+              r.header.call(hname)
+            rescue StandardError
+              nil
+            end
+            v.is_a?(String) ? v : nil
+          end
+        else
+          ->(r) { field_value(f, r) }
+        end
+
+      if f == "ip"
+        p4, p6 = sets.empty? ? [EMPTY, EMPTY] : sets.shift
+        n6 = p6.length >> 3
+        return lambda do |r|
+          next false if r.n4 < 0 && r.ip6.nil? # no address: false for every op, negatives included
+
+          hit = (r.n4 >= 0 && in_range4?(p4, r.n4)) || (!r.ip6.nil? && in_range6?(p6, n6, r.ip6))
+          negate ? !hit : hit
+        end
+      end
+      raw = c["v"]
+      values = raw.is_a?(Array) ? raw.map(&:to_s) : [raw.to_s]
+      case op
+      when "matches"
+        rx = compile_regex(values[0])
+        lambda do |r|
+          v = read.call(r)
+          !v.nil? && !rx.nil? && regex_hit?(rx, v)
+        end
+      when "contains"
+        needle = values[0]
+        lambda do |r|
+          v = read.call(r)
+          !v.nil? && text_hit? { v.include?(needle) }
+        end
+      when "starts_with"
+        prefix = values[0]
+        lambda do |r|
+          v = read.call(r)
+          !v.nil? && text_hit? { v.start_with?(prefix) }
+        end
+      else # is | is_not | is_in | not_in
+        members = values.to_set
+        lambda do |r|
+          v = read.call(r)
+          next false if v.nil?
+
+          negate ? !members.include?(v) : members.include?(v)
+        end
+      end
+    end
+
+    # meta.rules + the repeated 14/15 sections -> predicates, in evaluation order. A rule this SDK
+    # cannot compile (unknown action, no conditions) is dropped rather than guessed at.
+    def self.compile_rules(meta, v4s, v6s)
+      out = []
+      (meta["rules"] || []).each_with_index do |r, i|
+        action = r["action"].to_s
+        next unless ACTIONS.include?(action) # an action this SDK does not know: ignore the rule rather than guess
+
+        v4 = v4s.select { |s| s[0] == i }
+        v6 = v6s.select { |s| s[0] == i }
+        sets = Array.new([v4.length, v6.length].max) do |k|
+          [k < v4.length ? v4[k].slice(1, v4[k].length - 1) : EMPTY, k < v6.length ? v6[k].slice(1, v6[k].length - 1) : EMPTY]
+        end
+        conds = begin
+          (r["conds"] || []).map { |c| compile_cond(c, sets) }
+        rescue StandardError
+          next # a malformed rule is dropped, never enforced
+        end
+        out << CompiledRule.new(r["id"].to_s, action, conds) unless conds.empty? # a rule with no conditions would match everything
+      end
+      out
+    end
+
+    # Parses a BLK container (a byte String, or a Words view into one) + meta into a Snap. Raises
+    # ArgumentError on a malformed container — callers keep the previous snapshot, exactly like
+    # the edge collector does.
+    def self.parse_snapshot(binary, meta)
+      u = binary.is_a?(Words) ? binary : Words.new(binary)
+      fmt = u.length >= 2 ? FORMATS[u[0]] : nil
+      raise ArgumentError, "camada: not a BLK3 snapshot" unless fmt
+
+      count = u[1]
+      sec = {}
+      rule4 = []
+      rule6 = []
+      raise ArgumentError, "camada: truncated BLK3 header" if u.length < 2 + (count * 3)
+
+      count.times do |i|
+        t = u[2 + (i * 3)]
+        off = u[3 + (i * 3)]
+        ln = u[4 + (i * 3)]
+        raise ArgumentError, "camada: truncated BLK3 section" if off + ln > u.length
+
+        s = u.slice(off, ln)
+        case t
+        when 14 then rule4 << s # repeated, one per ip condition: kept in container order
+        when 15 then rule6 << s
+        else sec[t] = s
+        end
+      end
+      s6 = sec.fetch(5, EMPTY)
+      Snap.new(
+        version: meta["version"].to_s,
+        format: fmt,
+        s4: sec.fetch(1, EMPTY), e4: sec.fetch(2, EMPTY), idx4: sec[3] || Zeros.new(65_537), bm4: sec[4] || Zeros.new(524_288),
+        s6: s6, e6: sec.fetch(6, EMPTY), n6: s6.length / 4, bm6: sec[7] || Zeros.new(524_288),
+        asn_bm: sec[8] || Zeros.new(131_072), asn_extra: sec.fetch(9, EMPTY),
+        country: (meta["country"] || []).to_set,
+        tls: (meta["tls"] || []).to_set,
+        paths_exact: (meta["pathsExact"] || []).to_set,
+        paths_prefix: (meta["pathsPrefix"] || []).to_set,
+        paths_regex: (meta["pathsRegex"] || []).filter_map { |p| compile_regex(p) },
+        allow: range_set(sec.fetch(10, EMPTY), sec.fetch(11, EMPTY), meta["allow"]),
+        challenge: range_set(sec.fetch(12, EMPTY), sec.fetch(13, EMPTY), meta["challenge"]),
+        rules: compile_rules(meta, rule4, rule6)
+      )
+    end
+  end
+end

data/lib/camada/transport.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "zlib"
+require "stringio"
+
+module Camada
+  # The one HTTP seam. The engine, the snapshot client and the event queue speak to the analyst
+  # through a transport (anything responding to #call(HttpRequest) -> HttpResponse), so tests
+  # inject an in-process fake and production uses Net::HTTP. A transport never raises: a network
+  # failure is a status-0 response, which every caller treats as "keep what we have".
+  HttpRequest = Struct.new(:method, :url, :headers, :body, :timeout_s, keyword_init: true)
+  HttpResponse = Struct.new(
+    :status,  # 0 when the request never got an answer
+    :headers, # lower-cased names
+    :body,    # a binary String
+    keyword_init: true
+  )
+
+  module Transport
+    # Net::HTTP over the stdlib, gzip-aware (GET /snapshot ships ~5 MB that gzips to a few KB).
+    # Net::HTTP negotiates and decodes gzip on its own as long as the caller does not set
+    # accept-encoding by hand (that switches decode_content off), so that header is dropped here
+    # and the response is inflated below should a server still label it.
+    def self.net_http(req)
+      uri = URI.parse(req.url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = req.timeout_s
+      http.read_timeout = req.timeout_s
+      http.write_timeout = req.timeout_s
+      r = Net::HTTPGenericRequest.new(req.method, !req.body.nil?, true, uri.request_uri)
+      (req.headers || {}).each { |k, v| r[k] = v unless k.downcase == "accept-encoding" }
+      r.body = req.body if req.body
+      res = http.start { |h| h.request(r) }
+      headers = {}
+      res.each_header { |k, v| headers[k.downcase] = v }
+      response(res.code.to_i, headers, (res.body || "").b)
+    rescue StandardError
+      HttpResponse.new(status: 0, headers: {}, body: "".b)
+    end
+
+    def self.response(status, headers, body)
+      if headers["content-encoding"].to_s.downcase == "gzip"
+        begin
+          body = Zlib::GzipReader.new(StringIO.new(body)).read.b
+        rescue StandardError
+          return HttpResponse.new(status: 0, headers: headers, body: "".b) # a body we cannot read is no answer at all
+        end
+        headers.delete("content-encoding")
+      end
+      HttpResponse.new(status: status, headers: headers, body: body)
+    end
+
+    DEFAULT = method(:net_http)
+  end
+end

data/lib/camada/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Camada
+  # The SDK's wire identity: x-camada-sdk: @camada/ruby/<version>. This literal is the single
+  # source: camada.gemspec reads it at build, and the sibling drift guards (camada-backend,
+  # camada-web, camada-mkt) parse this file with /^\s*VERSION = "([^"]+)"/m the way they parse
+  # a package.json. Plain X.Y.Z only: the analyst's SDK_RE drops anything else.
+  VERSION = "0.1.0"
+  SDK_ID = "@camada/ruby/#{VERSION}".freeze
+end

data/lib/camada.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# camada for Ruby: inline enforcement of your tenant snapshot (ordered custom rules, then
+# allow, block, challenge), a first-party proof-of-work challenge and beacon, app-context events,
+# and batched wire events shipped off the request path. Fails open by design.
+#
+# Quickstart (env: CAMADA_KEY, plus CAMADA_INGEST_URL in dev):
+#
+#     # config.ru — any Rack app (Sinatra, Hanami, plain Rack)
+#     use Camada::Rack
+#     run App
+#
+#     # Rails: nothing to add — the Railtie inserts Camada::Rack first
+#
+#     # in a route
+#     Camada.script_tag(env)                              # the beacon tag for your HTML
+#     Camada.track(env, "login_failed", user: email)      # an outcome your handler knows
+#     halt(*Camada.serve_challenge(env)) if ...           # gate a route yourself
+require_relative "camada/version"
+require_relative "camada/constants"
+require_relative "camada/config"
+require_relative "camada/env"
+require_relative "camada/redact"
+require_relative "camada/ipparse"
+require_relative "camada/ip"
+require_relative "camada/guarded"
+require_relative "camada/transport"
+require_relative "camada/snapshot/parse"
+require_relative "camada/snapshot/match"
+require_relative "camada/snapshot/client"
+require_relative "camada/events/build"
+require_relative "camada/events/queue"
+require_relative "camada/challenge/format"
+require_relative "camada/challenge/verify"
+require_relative "camada/challenge/page"
+require_relative "camada/beacon_js"
+require_relative "camada/engine"
+require_relative "camada/body_proxy"
+require_relative "camada/rack"
+require_relative "camada/railtie"
+
+module Camada
+  @default = nil
+  @default_lock = Mutex.new
+
+  class << self
+    # The lazy singleton wired from the environment on first use (what the middleware shares).
+    def default(**opts)
+      @default_lock.synchronize { @default ||= create_engine(**opts) }
+    end
+
+    # Replaces the default engine (stopping the old one) — for tests and explicit wiring.
+    def configure(**opts)
+      @default_lock.synchronize do
+        @default&.stop
+        @default = create_engine(**opts)
+      end
+    end
+
+    # Stops and forgets the default engine; the next request builds a new one (tests).
+    def reset!
+      @default_lock.synchronize do
+        @default&.stop
+        @default = nil
+      end
+    end
+
+    # The engine that produced a request context, else the default: what the helpers resolve through.
+    def engine_for(ctx)
+      engine_of(ctx) || default
+    end
+
+    # The helpers take the Rack env (Sinatra's `env`, Rails' `request.env`); the middleware left
+    # the request context in env["camada"]. Each stands down silently when the middleware did not run.
+    def script_tag(env)
+      ctx = ctx_of(env)
+      engine_for(ctx).script_tag(ctx)
+    end
+
+    def track(env, event, user: nil)
+      ctx = ctx_of(env)
+      engine_for(ctx).track(ctx, event, user: user)
+    end
+
+    # A Rack triple [status, headers, [body]] to answer with (Sinatra: `halt(*answer)`) until the
+    # browser holds a valid _cch, then nil.
+    def serve_challenge(env)
+      ctx = ctx_of(env)
+      engine_for(ctx).serve_challenge(ctx)&.to_rack
+    end
+
+    private
+
+    def ctx_of(env)
+      ctx = env.is_a?(Hash) ? env["camada"] : nil
+      ctx.is_a?(Hash) ? ctx : nil
+    end
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: camada
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- camada
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-14 00:00:00.000000000 Z
+dependencies: []
+description: 'camada SDK for Ruby: inline enforcement of your snapshot (ordered custom
+  rules, then allow, block, challenge), first-party beacon and proof-of-work challenge,
+  batched event shipping. A Rack middleware for any Rack app (Sinatra, Rails via the
+  Railtie, Hanami, plain Rack).'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/camada.rb
+- lib/camada/beacon_js.rb
+- lib/camada/body_proxy.rb
+- lib/camada/challenge/format.rb
+- lib/camada/challenge/page.rb
+- lib/camada/challenge/verify.rb
+- lib/camada/config.rb
+- lib/camada/constants.rb
+- lib/camada/engine.rb
+- lib/camada/env.rb
+- lib/camada/events/build.rb
+- lib/camada/events/queue.rb
+- lib/camada/guarded.rb
+- lib/camada/ip.rb
+- lib/camada/ipparse.rb
+- lib/camada/rack.rb
+- lib/camada/railtie.rb
+- lib/camada/redact.rb
+- lib/camada/snapshot/client.rb
+- lib/camada/snapshot/match.rb
+- lib/camada/snapshot/parse.rb
+- lib/camada/transport.rb
+- lib/camada/version.rb
+homepage: https://github.com/camada-app/camada-ruby
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/camada-app/camada-ruby
+  source_code_uri: https://github.com/camada-app/camada-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'camada SDK for Ruby: inline enforcement of your snapshot, first-party beacon
+  and challenge, batched events'
+test_files: []