camada 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 628f9e7c2f9d061a56e7627695b0fccb7e7d3416d284878e9b931b3be4dc82bf
+  data.tar.gz: 735de6952ab6f22dc6e5c5c72773458d3ec9d165c6db9cb71dbc933a0e8fe401
+SHA512:
+  metadata.gz: 4d14f47f17124f90ebca0bcfba5cb314bec5f17d4807d2e2adcd0ba9ac58ba8bd5277983732c07ba06778222b69882ee46c7b2049439f7f58e4c180a7e961e1c
+  data.tar.gz: 76a85c3d6d4720d79c9f0c1ba223e7dfdc5109edeb16b9659ce876eccb19923e8ff4d3ff1a2c5df94260e52a41d4266c694fbd65ec99dbcf34e9fdfba0f18d30

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 camada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,199 @@
+# camada
+
+camada for Ruby: enforces the tenant snapshot inline (your ordered custom rules, then allow,
+block, challenge), serves a first-party proof-of-work challenge page and beacon, records the
+outcomes your handlers know (`Camada.track`), and ships wire events in batches off the request
+path. One gem with a Rack middleware that any Rack app mounts (Sinatra, Hanami, plain Rack) and
+a Railtie that mounts it for Rails — the `sentry-ruby` model. Fails open by design: a camada
+outage or bug never 5xxes your app.
+
+Not yet on RubyGems — install it from a sibling checkout: `gem "camada", path: "../camada-ruby"`
+in your Gemfile (as [`camada-ruby-example`](../camada-ruby-example) does); publishing is one
+decision with the npm packages (SDK-G01). Ruby 3.1 or newer, no runtime dependencies (stdlib
+only: `net/http`, `openssl`, `digest`, `json`, `securerandom`, `zlib`, `stringio`).
+
+## Quickstart
+
+```ruby
+# config.ru — Sinatra, Hanami, or any Rack app
+require "camada"
+use Camada::Rack      # first, so camada answers before routing
+run App
+
+# Rails — nothing to add: the Railtie inserts Camada::Rack at the top of the middleware stack
+```
+
+Env (printed by camada onboarding / `npm run seed` in dev):
+
+```
+CAMADA_KEY=<ingest_token>.<snap_token>
+CAMADA_INGEST_URL=http://localhost:8787        # dev only; defaults to production ingest
+```
+
+The middleware shares one lazy engine built from the environment on the first request. That
+build starts the snapshot poll on a thread and never blocks, so the request that triggered it is
+answered cold: it passes (fail open), and so does anything else that arrives before that first
+poll lands (a few hundred milliseconds against a local analyst; snapshot-size and network bound).
+To enforce from request 1, warm the engine at boot (an initializer, or `config.ru` before `run`)
+by waiting for the boot poll:
+
+```ruby
+engine = Camada.default          # builds the engine; the boot poll is already running on its thread
+if engine.snap                   # nil when CAMADA_KEY is unset or CAMADA_DISABLED=1
+  probe = Camada::Snapshot::MatchInput.new(ip: "0.0.0.0")
+  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+  while engine.snap.verdict(probe).reason == "cold" && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+    sleep 0.01                   # bounded: an unreachable analyst leaves it cold, and the app still fails open
+  end
+end
+```
+
+`snap.refresh` is not the warm-up: the boot poll holds the single-in-flight lock, so a
+synchronous `refresh` called right after `Camada.default` returns at once and the engine is
+still cold.
+
+Without `CAMADA_KEY` the engine is inert (one log line, no requests, no enforcement). An app that
+reads its own config builds the engine itself and hands it in:
+
+```ruby
+engine = Camada::Engine.new(env: { "CAMADA_KEY" => my_key, "CAMADA_INGEST_URL" => my_ingest })
+use Camada::Rack, engine
+```
+
+## What it does per request
+
+1. Keeps the snapshot fresh. A Ruby server is a long-lived process, so the default is a poll
+   thread at the cadence your tenant config sets (`poll_seconds`), with ETag/304 and gzip on the
+   wire. `CAMADA_SERVERLESS=1` switches to a per-request staleness check with no poll thread. Every
+   poll and event batch carries `x-camada-sdk: @camada/ruby/<version>`, and polls ask for
+   snapshot v5 (`x-camada-snapshot: 5`) — the container that carries your ordered custom rules.
+2. Resolves the client from the socket peer (`REMOTE_ADDR`), combined with `X-Forwarded-For`
+   only under your tenant's trusted-proxy config (or `CAMADA_TRUSTED_PROXY` locally). A forwarded
+   header on its own is never the ip: any caller can set it. **Never `request.ip`**:
+   `Rack::Request#ip` trusts `X-Forwarded-For` from anyone, which is exactly the spoof camada
+   refuses; the middleware reads `env["REMOTE_ADDR"]` and applies your trusted-proxy rules itself.
+3. Enforces before anything else, beacon endpoints included: your ordered custom rules first (first
+   match wins; they read ip, path, user-agent and request headers), then allow → block → challenge.
+   A block answers `403 Forbidden` with `x-block-reason`, `x-block-version` and, when a rule
+   decided, `x-block-rule`; its event ships with `blk` (and `rl`). A `warn` rule passes and stamps
+   `wrn`; a `skip` rule passes with nothing stamped. Cold (no snapshot yet) passes: fail open.
+4. Challenge: a `challenge` verdict gets the self-contained proof-of-work page (or 403 JSON for a
+   non-HTML request); `POST /__camada/challenge` verifies the solution, sets `_cch` (bound to the
+   ip, one hour) and 302s back. A request whose ip cannot be resolved is never challenged.
+5. Serves the beacon: `GET /_cam/b.js` (the `@camada/browser` build, vendored) and `POST /_cam/fp`
+   (≤ 32 KB, relayed onto the event batch as a `sig: 1` row with the ip camada resolved). Both
+   fall through to your app when the tenant switched the beacon off.
+6. Runs your app with `x-rid` and the `_sfp` session cookie on its response, and when the server
+   closes the response body ships one redacted event: method, host, path, scrubbed query, status,
+   latency, header names/sizes/order, the auth scheme (never the credential), cookie count (never
+   values), the matched route pattern when the framework names it (`sinatra.route`, Rails'
+   `route_uri_pattern`). An exception in your app ships as `st: 500` and propagates unchanged.
+
+## Options
+
+`Camada::Engine.new(...)` keyword arguments (also accepted by `Camada.default(...)` and
+`Camada::Rack.new(app, nil, ...)`); everything credential-shaped comes from the environment.
+
+| option | default | meaning |
+|---|---|---|
+| `env` | `ENV` | where `CAMADA_*` are read from (a Hash works too) |
+| `transport` | `Net::HTTP` | anything responding to `#call(HttpRequest) -> HttpResponse` (tests inject a fake) |
+| `refresh_s` | server-steered | poll cadence; set, it is pinned |
+| `challenge` | `true` | serve the proof-of-work page for challenge verdicts (`CAMADA_CHALLENGE=0` too) |
+| `challenge_path` | `/__camada/challenge` | where the page posts its solution |
+| `snapshot_version` | `5` | 4 drops your custom rules; 3 the allow/challenge sides too |
+| `script_path` / `fp_path` | `/_cam/b.js` / `/_cam/fp` | the beacon endpoints; keep them in one directory |
+
+Env: `CAMADA_KEY` (or `CAMADA_TOKEN` + `CAMADA_SNAPSHOT_TOKEN`), `CAMADA_INGEST_URL`,
+`CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY` (`none | vercel | hops:N | cidrs:a,b`),
+`CAMADA_SERVERLESS=1`, `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1` (checked per
+request; set at boot, no threads start at all).
+
+## The first-party beacon
+
+```ruby
+# Sinatra: `env` is the Rack env; Rails: request.env
+"<html><head>#{Camada.script_tag(env)}</head>…"
+```
+
+The tag is `<script src="/_cam/b.js?r=<rid>" async>`, so the beacon joins the page view that
+served it. Move both paths with `script_path` / `fp_path` when `/_cam/` is not yours; the script
+derives the post path from its own URL, so the two must share a directory.
+
+## App-context events
+
+```ruby
+Camada.track(env, "login_failed", user: email)
+```
+
+The identifier is HMAC-hashed in-process with your ingest token; the raw value never reaches the
+queue. `Camada.track` never raises and is a no-op on a request the middleware did not run for. The
+event name is free-form; the analyst's app-context rules read this vocabulary:
+
+| event | when |
+|---|---|
+| `login_failed` / `login_succeeded` | a login attempt settled; pass `user:` so attempts per account can be counted |
+| `signup` | an account was created |
+| `password_reset` | a reset was requested |
+| `mfa_failed` | a second factor was rejected |
+| `payment_failed` / `payment_succeeded` | a payment authorisation settled |
+| `coupon_failed` | a promo/voucher code was rejected |
+
+A route you gate yourself: `Camada.serve_challenge(env)` returns a Rack triple
+`[status, headers, [body]]` to answer with (Sinatra: `halt(*answer)`) until the browser holds a
+valid `_cch`, then `nil`.
+
+## What this tap can see
+
+`sdk-ruby` is an in-app tap: status, latency, session, the beacon's browser signals and your
+outcomes. Puma hands the env to Rack as binary strings; the middleware reads them as UTF-8 with
+invalid bytes replaced (U+FFFD) before matching and shipping, so a stray high byte in a header
+neither escapes a rule nor costs the batch it rides in. The Rack env carries no wire header order (`hord` is the env's order), so the analyst
+reads no HEADER_ORDER signal from this tap, and it never scores the absence of header order, ASN,
+country or a TLS fingerprint against a request; ASN and country it resolves itself. Enforcement
+at this position covers ip, path, user-agent and header conditions — ASN, country and TLS entries
+fail open in-app. `matches` patterns are JS regexes read by Ruby's Onigmo: named groups are
+native, `[^]` and `\cX` are translated, `^`/`$` become `\A`/`\z` (Ruby's are line anchors,
+JS's are not), `\d`/`\w`/`\b` are ASCII as in JS; a spelling Ruby still rejects never matches
+here (and never raises), while it does at the edge.
+
+## Deploying it
+
+- Every worker process polls its own snapshot (about 5 MB resident, read a word at a time — never
+  expanded into Ruby Integers) and flushes its own batches; the tenant's `poll_seconds` keeps the
+  cadence honest across a fleet.
+- Threads do not survive a fork. Ruby has no fork hook, so the SDK compares `Process.pid` on every
+  call and starts over in a forked worker: new locks, an empty queue, its poll and flush threads
+  restarted. Puma cluster mode with `preload_app!`, Unicorn and Passenger need nothing added.
+- Pending events drain at interpreter exit within half a second (`at_exit`). No signal handlers
+  are installed — an app owns its own shutdown — so a worker killed by SIGKILL, or by SIGTERM
+  without a handler, may drop its last batch.
+- Serverless: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
+- The middleware writes lower-case header names; it appends `set-cookie` as an Array under Rack 3
+  and joins cookies with `"\n"` under Rack 2. It never requires `rack` itself.
+
+## Fail open
+
+Every entry point runs inside the fail-open envelope: a dead ingest drops telemetry (logged at
+most once a minute, one line, no backtrace), a corrupt snapshot keeps the previous one, a bug in
+the gem costs the request its join, never its response. `CAMADA_DISABLED=1` bypasses everything.
+
+## Development
+
+```
+bundle install && bundle exec rubocop && bundle exec rspec
+```
+
+No type checker: the gem has no runtime dependencies and a Sorbet or Steep setup would add a
+toolchain (and RBS signatures for every stdlib seam) for a 2.5k-line port whose behaviour is
+pinned by the golden fixtures instead; it is deferred, not refused. A Rails example app is
+deferred the same way — the Railtie ships in the gem, the example repo is Sinatra.
+
+The suite reads the golden snapshot fixtures from the `camada-core` sibling checkout and pins the
+vendored beacon to `camada-browser/dist/auto.global.js` (`npm run build` there first, then
+`ruby scripts/sync_beacon.rb` after a beacon release). Both fail by name when the checkout is
+missing rather than skipping (`CAMADA_FIXTURES_DIR`, `CAMADA_BROWSER_DIST` override the paths).
+
+[`camada-ruby-example`](../camada-ruby-example) is the hand-test bench (Sinatra under Puma on
+:3004), and `node scripts/e2e-sdk-ruby.mjs` in `camada/edge-analyst` drives it against a seeded
+local analyst over real HTTP, cold first request included.

data/lib/camada/beacon_js.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# GENERATED by scripts/sync_beacon.rb — do not edit. The first-party beacon (@camada/browser's
+# dist/auto.global.js) vendored as a String literal: served at /_cam/b.js with no runtime file
+# read. spec/beacon_js_spec.rb pins it to the sibling build byte for byte.
+module Camada
+  BEACON_VERSION = "0.2.0"
+  BEACON_SHA256 = "f0de88bef775d44b76e363d9cb6b87da7bb908172d686921326b635ff03f012b"
+  BEACON_JS = "\"use strict\";(()=>{var k=\"0.2.0\";var _=\"@camada/browser\";var b=`${_}/${k}`;function n(t){try{return t()}catch{return null}}function x(t){let e=2166136261;for(let i=0;i<t.length;i++)e^=t.charCodeAt(i),e=Math.imul(e,16777619);return(e>>>0).toString(16)}function M(){let t=document.createElement(\"canvas\");t.width=240,t.height=60;let e=t.getContext(\"2d\");return e?(e.textBaseline=\"alphabetic\",e.fillStyle=\"#f60\",e.fillRect(120,5,60,20),e.fillStyle=\"#069\",e.font=\"15px Arial\",e.fillText(\"Sfp\\u2603 1.0\",2,15),e.fillStyle=\"rgba(102,204,0,0.7)\",e.font=\"17px Times\",e.fillText(\"Sfp\\u2603 1.0\",4,45),x(t.toDataURL())):null}function R(){let t=document.createElement(\"canvas\"),e=t.getContext(\"webgl\")||t.getContext(\"experimental-webgl\");if(!e)return null;let i=e.getExtension(\"WEBGL_debug_renderer_info\");return{v:i?e.getParameter(i.UNMASKED_VENDOR_WEBGL):e.getParameter(e.VENDOR),r:i?e.getParameter(i.UNMASKED_RENDERER_WEBGL):e.getParameter(e.RENDERER)}}function S(){return x([Math.tan(-1e300),Math.sinh(1),Math.expm1(1),Math.cbrt(100),Math.log1p(10),Math.atanh(.5)].join(\"|\"))}var N=/^\\$?cdc_|^__webdriver|^__selenium|^__nightmare|^__playwright|^callPhantom/,L=/^\\$?cdc_|^__webdriver|^__selenium|^__nightmare|^__playwright|^callPhantom|^_phantom/;function j(){let t=document,e=navigator,i=window,o=0;for(let s in t)N.test(s)&&o++;for(let s in i)L.test(s)&&o++;return{wd:e.webdriver===!0?1:0,cdc:o,chrome:typeof i.chrome<\"u\"?1:0,plugins:e.plugins?e.plugins.length:-1,langs:e.languages?e.languages.length:-1,outer:window.outerWidth===0&&window.outerHeight===0?1:0,perm:n(()=>Notification.permission),pdf:typeof e.pdfViewerEnabled==\"boolean\"?e.pdfViewerEnabled?1:0:-1,err:n(()=>{try{null.x}catch(s){let c=s.stack;return c?c.split(`\n`).length:0}})}}function T({endpoint:t,rid:e}){let i=e||null,o=performance.now(),s=0,c=0,m=0,h=0,f=0,u=null;function l(){u===null&&(u=Math.round(performance.now()-o))}addEventListener(\"mousemove\",()=>{s++,l()},{passive:!0}),addEventListener(\"scroll\",()=>{c++,l()},{passive:!0}),addEventListener(\"keydown\",()=>{m++,l()},{passive:!0}),addEventListener(\"touchstart\",()=>{h++,l()},{passive:!0}),addEventListener(\"click\",()=>{f++,l()},{passive:!0});function w(){let r=navigator,a=n(()=>performance.getEntriesByType(\"navigation\")[0]),D=n(()=>{let p=performance.getEntriesByType(\"paint\");return p.length?Math.round(p[p.length-1].startTime):null}),d=n(()=>r.connection)||{};return{sdk:b,rid:i,ts:Date.now(),scr:n(()=>[screen.width,screen.height,screen.availWidth,screen.availHeight,screen.colorDepth]),win:n(()=>[window.innerWidth,window.innerHeight,window.outerWidth,window.outerHeight]),dpr:n(()=>window.devicePixelRatio),tz:n(()=>Intl.DateTimeFormat().resolvedOptions().timeZone),tzo:n(()=>new Date().getTimezoneOffset()),lang:n(()=>r.language),langs:n(()=>r.languages?Array.prototype.slice.call(r.languages,0,5):null),plat:n(()=>r.platform),cores:n(()=>r.hardwareConcurrency),mem:n(()=>r.deviceMemory),touch:n(()=>r.maxTouchPoints),ua:n(()=>r.userAgent),dnt:n(()=>r.doNotTrack),cookies:n(()=>r.cookieEnabled?1:0),conn:n(()=>[d.effectiveType,d.rtt,d.downlink,d.saveData?1:0]),gl:n(R),cv:n(M),mf:n(S),auto:n(j),vis:n(()=>document.visibilityState),focus:n(()=>document.hasFocus()?1:0),timing:a?[Math.round(a.domContentLoadedEventEnd),Math.round(a.loadEventEnd),Math.round(a.responseEnd-a.requestStart)]:null,paint:D,input:{moves:s,scrolls:c,keys:m,touches:h,clicks:f,first:u,at:Math.round(performance.now()-o)}}}function v(r){let a=JSON.stringify(r?Object.assign(w(),{hi:r}):w());navigator.sendBeacon&&navigator.sendBeacon(t,new Blob([a],{type:\"application/json\"}))||fetch(t,{method:\"POST\",body:a,keepalive:!0,headers:{\"content-type\":\"application/json\"}}).catch(()=>{})}let g=navigator.userAgentData,E=g&&g.getHighEntropyValues?g.getHighEntropyValues([\"architecture\",\"bitness\",\"model\",\"platformVersion\",\"fullVersionList\"]).catch(()=>null):Promise.resolve(null);setTimeout(()=>{E.then(v)},2e3),addEventListener(\"pagehide\",()=>{E.then(r=>{v(r)})},{once:!0})}function O(t){let e=new URL(t,\"http://_\"),i=e.pathname.split(\"/\");return i[i.length-1]=\"fp\",{endpoint:i.join(\"/\"),rid:e.searchParams.get(\"r\")}}(function(){try{let t=document.currentScript,e=t&&t.src;if(!e)return;let{endpoint:i,rid:o}=O(e);T({endpoint:i,rid:o})}catch{}})();})();\n"
+end

data/lib/camada/body_proxy.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Camada
+  # Wraps the app's Rack body so the block runs exactly once, when the server closes the body
+  # (after the last byte, PEP 3333's close() in Rack terms). Nothing here requires "rack": the
+  # gem stays dependency-free, so this mirrors Rack::BodyProxy's shape instead: everything but
+  # close is delegated, and the proxy responds to a body method only when the inner body does.
+  # That last part is load-bearing — a Body that answers `each` is an Enumerable Body to every
+  # server (Rack SPEC), so a proxy with its own `each` would turn a Rack 3 streaming body
+  # (call-only) into a NoMethodError at the socket.
+  class BodyProxy
+    def initialize(body, &block)
+      @body = body
+      @block = block
+      @closed = false
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      begin
+        @body.close if @body.respond_to?(:close)
+      ensure
+        @block.call
+      end
+    end
+
+    def closed? = @closed
+
+    def respond_to_missing?(name, include_all = false)
+      name != :to_str && @body.respond_to?(name, include_all)
+    end
+
+    # each, call (a streaming body), to_path (a file the server may sendfile) and to_ary pass
+    # through. A body consumed via to_ary must close itself (SPEC), so the proxy does it there.
+    def method_missing(name, ...)
+      return super if name == :to_str
+      return @body.__send__(name, ...) unless name == :to_ary
+
+      begin
+        @body.__send__(name, ...)
+      ensure
+        close
+      end
+    end
+  end
+end

data/lib/camada/challenge/format.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Camada
+  # Wire constants and pure helpers for the SDK-served challenge (contracts §D2), ported from
+  # @camada/core src/challenge/format.ts. Nothing here does crypto; verify.rb supplies HMAC and
+  # SHA-256 from the stdlib, so the format has exactly one definition across the family.
+  module Challenge
+    CHALLENGE_COOKIE = "_cch"
+    CHALLENGE_TTL_MS = 3_600_000 # 1 h (contract)
+    POW_BITS = 16                # leading zero bits of SHA-256("<nonce>.<solution>")
+    NONCE_HEX = 32               # the nonce is the first 32 hex chars of the HMAC
+    DAY_MS = 86_400_000
+    MAX_RETURN_TO = 2048
+    MAX_SOLUTION = 32
+
+    def self.utc_day(now_ms) = now_ms / DAY_MS
+
+    # Domain-separated messages: a nonce HMAC can never be replayed as a cookie HMAC.
+    def self.nonce_message(ip, day) = "camada-challenge-nonce|#{ip}|#{day}"
+    def self.token_message(ip, exp) = "camada-challenge-token|#{ip}|#{exp}"
+
+    def self.split_token(value)
+      return nil if value.nil? || value.empty?
+
+      dot = value.index(".")
+      return nil if dot.nil? || dot <= 0
+
+      exp = Integer(value[0, dot], 10, exception: false)
+      return nil if exp.nil?
+
+      mac = value[(dot + 1)..]
+      mac.empty? ? nil : [exp, mac]
+    end
+
+    # Constant-time for equal-length strings; length itself is not a secret here.
+    def self.safe_equal?(a, b)
+      a.bytesize == b.bytesize && OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    # True when the hex digest starts with `bits` zero bits.
+    def self.pow_ok?(hex_digest, bits = POW_BITS)
+      nibbles = bits >> 2
+      rest = bits & 3
+      return false if hex_digest.length < nibbles + (rest == 0 ? 0 : 1)
+      return false if nibbles.times.any? { |i| hex_digest[i] != "0" }
+      return true if rest == 0
+
+      v = Integer(hex_digest[nibbles], 16, exception: false)
+      return false if v.nil?
+
+      (v >> (4 - rest)) == 0
+    end
+
+    def self.solution_shape_ok?(solution)
+      !solution.nil? && !solution.empty? && solution.length <= MAX_SOLUTION
+    end
+
+    def self.challenge_cookie(value, secure)
+      "#{CHALLENGE_COOKIE}=#{value}; Path=/; Max-Age=#{CHALLENGE_TTL_MS / 1000}; HttpOnly; SameSite=Lax#{"; Secure" if secure}"
+    end
+
+    # Only a printable-ASCII same-site absolute path survives: never an absolute URL, a
+    # protocol-relative '//host' redirect, a control character, or something absurdly long.
+    def self.safe_return_to(raw)
+      return "/" if raw.nil? || raw.empty? || raw.length > MAX_RETURN_TO
+      return "/" if raw[0] != "/" || (raw.length > 1 && "/\\".include?(raw[1]))
+      return "/" unless raw.match?(/\A[\x21-\x7e]+\z/)
+
+      raw
+    end
+
+    # A challenge page is only worth serving to a top-level HTML navigation (contract §D2).
+    def self.wants_html?(accept, sec_fetch_dest)
+      return false if accept.nil? || !accept.include?("text/html")
+
+      sec_fetch_dest.nil? || sec_fetch_dest.empty? || sec_fetch_dest == "document"
+    end
+
+    def self.escape_attr(s)
+      s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;").gsub("'", "&#39;")
+    end
+
+    # Safe to drop inside an inline <script>: `<` is escaped so no value can close the element early.
+    def self.escape_script(s) = JSON.generate(s).gsub("<", "\\u003c")
+
+    # application/x-www-form-urlencoded, last value wins. Never raises on junk: an invalid
+    # %-escape is kept as is, invalid UTF-8 is replaced.
+    def self.parse_form_body(body)
+      out = {}
+      body.split("&").each do |pair|
+        next if pair.empty?
+
+        eq = pair.index("=")
+        k = eq.nil? ? pair : pair[0, eq]
+        v = eq.nil? ? "" : pair[(eq + 1)..]
+        out[unquote(k)] = unquote(v)
+      end
+      out
+    end
+
+    def self.unquote(s)
+      s.tr("+", " ").b.gsub(/%[0-9a-fA-F]{2}/) { |m| [m[1, 2].hex].pack("C") }.force_encoding("UTF-8").scrub
+    end
+  end
+end

data/lib/camada/challenge/page.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "format"
+
+module Camada
+  module Challenge
+    # The 403 challenge page: one self-contained HTML document, no external assets, no-store —
+    # byte-for-byte the page @camada/core serves (src/challenge/page.ts). The inline solver hunts a
+    # counter whose SHA-256(`${nonce}.${counter}`) starts with 16 zero bits (~65k hashes, tens of
+    # milliseconds), fills the hidden form and submits it. The form POST means the browser follows
+    # the verify endpoint's 302 natively, so the cookie is set and the original URL is re-fetched
+    # without any fetch/CORS/cookie subtleties.
+    #
+    # The page carries its own SHA-256 rather than calling crypto.subtle: subtle is undefined on
+    # non-secure origins (plain http on a LAN host), and 65k awaited digests would be slow anyway.
+
+    # FIPS 180-4 round constants (cube roots of the first 64 primes).
+    K = "0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5," \
+        "0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174," \
+        "0xe49b69c1,0xefbe4786,0xfc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da," \
+        "0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x6ca6351,0x14292967," \
+        "0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85," \
+        "0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070," \
+        "0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3," \
+        "0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2"
+
+    # One SHA-256 over an ASCII string. Returns the 8 state words; the solver reads H[0] only
+    # (16 leading zero bits === H[0] >>> 16 === 0, which is exactly the server's pow_ok?(hex, 16)).
+    SOLVER = [
+      "\nvar __camadaK=[#{K}];\n",
+      "function __camadaRr(x,n){return (x>>>n)|(x<<(32-n))}\n",
+      "function __camadaSha256Words(msg){\n",
+      "  var K=__camadaK,rr=__camadaRr,l=msg.length,wl=(((l+9+63)>>6)<<4),M=new Uint32Array(wl),i;\n",
+      "  for(i=0;i<l;i++)M[i>>2]|=(msg.charCodeAt(i)&255)<<(24-(i%4)*8);\n",
+      "  M[l>>2]|=0x80<<(24-(l%4)*8);\n",
+      "  M[wl-1]=l*8;\n",
+      "  var H=[0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19];\n",
+      "  var W=new Uint32Array(64),bi,t;\n",
+      "  for(bi=0;bi<wl;bi+=16){\n",
+      "    for(t=0;t<16;t++)W[t]=M[bi+t];\n",
+      "    for(t=16;t<64;t++){var x=W[t-15],y=W[t-2];\n",
+      "      W[t]=(W[t-16]+(rr(x,7)^rr(x,18)^(x>>>3))+W[t-7]+(rr(y,17)^rr(y,19)^(y>>>10)))>>>0}\n",
+      "    var a=H[0],b=H[1],c=H[2],d=H[3],e=H[4],f=H[5],g=H[6],h=H[7];\n",
+      "    for(t=0;t<64;t++){\n",
+      "      var t1=(h+(rr(e,6)^rr(e,11)^rr(e,25))+((e&f)^(~e&g))+K[t]+W[t])>>>0;\n",
+      "      var t2=((rr(a,2)^rr(a,13)^rr(a,22))+((a&b)^(a&c)^(b&c)))>>>0;\n",
+      "      h=g;g=f;f=e;e=(d+t1)>>>0;d=c;c=b;b=a;a=(t1+t2)>>>0}\n",
+      "    H[0]=(H[0]+a)>>>0;H[1]=(H[1]+b)>>>0;H[2]=(H[2]+c)>>>0;H[3]=(H[3]+d)>>>0;\n",
+      "    H[4]=(H[4]+e)>>>0;H[5]=(H[5]+f)>>>0;H[6]=(H[6]+g)>>>0;H[7]=(H[7]+h)>>>0}\n",
+      "  return H}\n",
+      "function __camadaSha256Hex(msg){\n",
+      "  var H=__camadaSha256Words(msg),s='',i;\n",
+      "  for(i=0;i<8;i++)s+=('00000000'+H[i].toString(16)).slice(-8);\n",
+      "  return s}\n"
+    ].join.freeze
+
+    STYLE = [
+      ":root{color-scheme:light}\n",
+      "body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#fafafa;color:#1a1a1a;",
+      "font:16px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}\n",
+      "main{max-width:28rem;padding:2rem;text-align:center}\n",
+      "h1{font-size:1.25rem;margin:0 0 .5rem}\n",
+      "p{margin:.25rem 0;color:#555}\n",
+      ".bar{margin:1.5rem auto 0;width:12rem;height:4px;border-radius:2px;background:#e5e5e5;overflow:hidden}\n",
+      ".bar i{display:block;height:100%;width:30%;background:#1a1a1a;animation:camada-slide 1.1s ease-in-out infinite}\n",
+      "@keyframes camada-slide{0%{transform:translateX(-120%)}100%{transform:translateX(400%)}}\n"
+    ].join.freeze
+
+    # `action` is the verify endpoint path; `to` has already been through safe_return_to.
+    def self.challenge_page(nonce:, action:, to:, bits: POW_BITS)
+      bits = bits.clamp(1, 32) # shift 32-bits must stay in range
+      [
+        "<!doctype html>\n",
+        "<html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n",
+        "<title>Checking your browser</title>\n",
+        "<style>\n#{STYLE}</style></head>\n",
+        "<body>\n",
+        "<main>\n",
+        "<h1>Checking your browser</h1>\n",
+        "<p id=\"camada-msg\">This takes a moment. It runs entirely in your browser.</p>\n",
+        "<noscript><p>JavaScript is required to continue.</p></noscript>\n",
+        "<div class=\"bar\"><i></i></div>\n",
+        "</main>\n",
+        "<form id=\"camada-f\" method=\"POST\" action=\"#{escape_attr(action)}\">\n",
+        "<input type=\"hidden\" name=\"nonce\" value=\"#{escape_attr(nonce)}\">\n",
+        "<input type=\"hidden\" name=\"solution\" id=\"camada-s\">\n",
+        "<input type=\"hidden\" name=\"to\" value=\"#{escape_attr(to)}\">\n",
+        "</form>\n",
+        "<script>#{SOLVER}\n",
+        "(function(){\n",
+        "  if(typeof window==='undefined'||window.__camadaAutostart===false)return;\n",
+        "  var nonce=#{escape_script(nonce)},shift=#{32 - bits};\n",
+        "  function go(){\n",
+        "    for(var n=0;n<5000000;n++){\n",
+        "      if((__camadaSha256Words(nonce+'.'+n)[0]>>>shift)===0){\n",
+        "        document.getElementById('camada-s').value=String(n);\n",
+        "        document.getElementById('camada-f').submit();\n",
+        "        return}}\n",
+        "    document.getElementById('camada-msg').textContent='Could not complete the check. Please reload.'}\n",
+        "  setTimeout(go,30);\n",
+        "})();\n",
+        "</script>\n",
+        "</body></html>"
+      ].join
+    end
+  end
+end

data/lib/camada/challenge/verify.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "digest"
+require "openssl"
+require_relative "format"
+
+module Camada
+  module Challenge
+    # The challenge kit over OpenSSL's HMAC-SHA256 and Digest's SHA-256, ported from
+    # @camada/core src/challenge/verify.ts. Synchronous, so the engine's handle stays a plain method.
+    class Kit
+      def initialize(secret)
+        @secret = secret
+      end
+
+      # Stateless per-(ip, UTC day) nonce; the verify endpoint recomputes it, nothing is stored.
+      def nonce(ip, now_ms) = at(ip, Challenge.utc_day(now_ms))
+
+      # Yesterday still passes: a solve started before midnight UTC must not be thrown away.
+      # So one solved (nonce, solution) pair is replayable from its own IP for up to ~48 h,
+      # minting a fresh 1 h cookie each time. That is the price of a stateless nonce (§D2) and
+      # it is deliberate — do not "fix" it into something that needs shared server state.
+      def nonce_valid?(ip, now_ms, nonce)
+        return false if ip.nil? || ip.empty? || nonce.nil? || nonce.length != NONCE_HEX
+
+        day = Challenge.utc_day(now_ms)
+        Challenge.safe_equal?(nonce, at(ip, day)) || Challenge.safe_equal?(nonce, at(ip, day - 1))
+      end
+
+      def issue(ip, now_ms)
+        exp = now_ms + CHALLENGE_TTL_MS
+        "#{exp}.#{hmac(Challenge.token_message(ip, exp))}"
+      end
+
+      # A nil ip is refused outright: without one the token is bound to nothing, so a single
+      # solve would mint a cookie every other unidentified client could present. Adapters must
+      # fail open (serve no challenge) rather than challenge a client they cannot identify.
+      def token_valid?(ip, now_ms, cookie_value)
+        return false if ip.nil? || ip.empty?
+
+        t = Challenge.split_token(cookie_value)
+        return false if t.nil?
+
+        exp, mac = t
+        return false if exp <= now_ms || exp > now_ms + CHALLENGE_TTL_MS
+
+        Challenge.safe_equal?(mac, hmac(Challenge.token_message(ip, exp)))
+      end
+
+      # Proof of work ONLY. Never call it without a passing nonce_valid? for the same nonce.
+      def solution_ok?(nonce, solution)
+        Challenge.solution_shape_ok?(solution) && Challenge.pow_ok?(Digest::SHA256.hexdigest("#{nonce}.#{solution}"))
+      end
+
+      # The whole submission: the nonce is ours and unexpired, and the work is done.
+      def verify?(ip, now_ms, nonce, solution)
+        nonce_valid?(ip, now_ms, nonce) && solution_ok?(nonce, solution)
+      end
+
+      private
+
+      def hmac(msg) = OpenSSL::HMAC.hexdigest("SHA256", @secret, msg)
+      def at(ip, day) = hmac(Challenge.nonce_message(ip, day))[0, NONCE_HEX]
+    end
+
+    def self.create_challenge(secret) = Kit.new(secret)
+  end
+end

data/lib/camada/config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Camada
+  # Configuration shapes shared by the client and the engine. `parse_key` splits CAMADA_KEY. The
+  # remote config GET /snapshot hands back in x-camada-config (whitelisted server-side) is a
+  # plain Hash: { tenant, beacon, sample, exclude, trusted_proxy, poll_seconds } with string keys,
+  # as JSON delivers them. A trusted-proxy config mirrors the server-validated tenant config
+  # (edge-analyst src/tenant-config.js): {mode: none} | {mode: hops, hops: N} | {mode: cidrs, cidrs: [...]} | {mode: vercel}.
+  module Config
+    # CAMADA_KEY is `<ingest_token>.<snap_token>` (printed by reconcile instructions and seed).
+    def self.parse_key(key)
+      return nil if key.nil? || key.empty?
+
+      dot = key.index(".")
+      return nil if dot.nil? || dot <= 0 || dot == key.length - 1
+
+      [key[0, dot], key[(dot + 1)..]]
+    end
+
+    # CAMADA_TRUSTED_PROXY: none | vercel | hops:N | cidrs:a,b. Unset or malformed returns nil,
+    # which callers treat as "defer to the server-delivered tenant config", never as trust.
+    def self.parse_trusted_proxy_env(v)
+      return nil if v.nil? || v.empty?
+      return { "mode" => "none" } if v == "none"
+      return { "mode" => "vercel" } if v == "vercel"
+
+      if v.start_with?("hops:")
+        hops = Integer(v[5..], 10, exception: false)
+        return hops && hops >= 1 ? { "mode" => "hops", "hops" => hops } : nil
+      end
+      if v.start_with?("cidrs:")
+        cidrs = v[6..].split(",").map(&:strip).reject(&:empty?)
+        return cidrs.empty? ? nil : { "mode" => "cidrs", "cidrs" => cidrs }
+      end
+      nil
+    end
+  end
+end

data/lib/camada/constants.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Camada
+  # Tap identifier this SDK claims on the wire. The server validates against its own enum and
+  # derives the capability mask itself (edge-analyst src/capabilities.js): an SDK can never grant
+  # itself capability bits, only name its position — and an unknown name is silently read as a
+  # proxy, so this literal is load-bearing.
+  TAP = "sdk-ruby"
+
+  DEFAULT_REFRESH_S = 30.0
+  # 5 carries the tenant's ordered custom rules (§D3); a tenant without one is answered with the next container down.
+  DEFAULT_SNAPSHOT_VERSION = 5
+  KILL_SWITCH_ENV = "CAMADA_DISABLED"
+
+  SCRIPT_PATH = "/_cam/b.js"
+  FP_PATH = "/_cam/fp"
+  FP_MAX = 32 * 1024                # matches the server's /fp cap: never accept what ingest will 413
+  CHALLENGE_PATH = "/__camada/challenge"
+  BODY_MAX = 4 * 1024               # the verify form is ~120 bytes; anything larger is not ours
+
+  SESSION_COOKIE = "_sfp"           # same cookie as the edge collector: sid/ns comparable across taps
+  SESSION_MAX_AGE = 2_592_000       # 30 days
+
+  # nil for nil or "", else the string: the one nil-or-empty helper every module reads through.
+  def self.present(s) = s.nil? || s.empty? ? nil : s
+
+  # JSON.parse that answers nil for anything that is not JSON (a config header, a beacon body).
+  def self.parse_json(s)
+    JSON.parse(s)
+  rescue JSON::ParserError
+    nil
+  end
+end