camada 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 628f9e7c2f9d061a56e7627695b0fccb7e7d3416d284878e9b931b3be4dc82bf
-  data.tar.gz: 735de6952ab6f22dc6e5c5c72773458d3ec9d165c6db9cb71dbc933a0e8fe401
+  metadata.gz: 450a1a841ac03fb9490c0a6c1c3e45d62b0eec927795bb3fc3b2064f89432349
+  data.tar.gz: 8cd0ffee6f1686a7ad8150094898f3faaaff7f7b797306b5bb2af936a05ccc84
 SHA512:
-  metadata.gz: 4d14f47f17124f90ebca0bcfba5cb314bec5f17d4807d2e2adcd0ba9ac58ba8bd5277983732c07ba06778222b69882ee46c7b2049439f7f58e4c180a7e961e1c
-  data.tar.gz: 76a85c3d6d4720d79c9f0c1ba223e7dfdc5109edeb16b9659ce876eccb19923e8ff4d3ff1a2c5df94260e52a41d4266c694fbd65ec99dbcf34e9fdfba0f18d30
+  metadata.gz: 27a5225cff7c94d36f2d5d1d85e91a4304bc71d7edff69c5706ffb9cba903132e67723e650f991a1445abd96f402ac3b2fa920240bc6184e82441870dc0a94cb
+  data.tar.gz: 677d632f45dab7351fd8982c396335a9ab02b8bfc1f6598301b4b1c334d520922d6b11e543353e314b8c5aead17b0b66ae4aefbaac6e5ccec0a9e773aa066f58

data/README.md

@@ -8,7 +8,7 @@ a Railtie that mounts it for Rails — the `sentry-ruby` model. Fails open by de
 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
+in your Gemfile (as [`camada-ruby-example`](https://github.com/camada-app/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`).
 
@@ -23,7 +23,7 @@ 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):
+Env (the key is printed once when you create a project in the app):
 
 ```
 CAMADA_KEY=<ingest_token>.<snap_token>
@@ -83,11 +83,11 @@ use Camada::Rack, engine
 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.
+6. Runs your app with `x-rid` (the rid of the request's event row; never on a 101 handshake) 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
 
@@ -194,6 +194,6 @@ vendored beacon to `camada-browser/dist/auto.global.js` (`npm run build` there f
 `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
+[`camada-ruby-example`](https://github.com/camada-app/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

@@ -4,7 +4,7 @@
 # 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"
+  BEACON_VERSION = "0.3.0"
+  BEACON_SHA256 = "0abf522f9d0004ae798ba22fec74e935f545f787847574c4800662d00d522e95"
+  BEACON_JS = "\"use strict\";(()=>{var k=\"0.3.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/engine.rb

@@ -204,6 +204,7 @@ module Camada
       return INERT if disabled? || @snap.nil?
 
       t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      ts0 = now_ms # ts is the request start, the moment dur counts from
       @snap.ensure_fresh
       ip = client_ip(req)
 
@@ -265,6 +266,7 @@ module Camada
         next if ctx["challenged"] || excluded || !sampled
 
         ev = event(req, rid, sid, new_session, ip)
+        ev["ts"] = ts0
         ev["st"] = status
         ev["dur"] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).to_i
         ev["rt"] = req.route if req.route

data/lib/camada/env.rb

@@ -21,9 +21,8 @@ module Camada
   )
 
   class Env
-    # PLACEHOLDER default, the same one @camada/node and camada-python carry — confirm the
-    # production ingest domain before any RubyGems publish.
-    DEFAULT_INGEST_URL = "https://in.camada.dev"
+    # Production ingest; CAMADA_INGEST_URL overrides it.
+    DEFAULT_INGEST_URL = "https://in.camada.app"
 
     # nil (SDK stays inert, one log line) rather than raising on bad config. `env` is anything
     # answering #[] with strings: ENV, or a Hash.

data/lib/camada/guarded.rb

@@ -4,7 +4,7 @@ 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
+    @last_log = nil # monotonic seconds of the last line; nil until the first one
     @logger = nil
 
     class << self
@@ -12,8 +12,10 @@ module Camada
       attr_accessor :logger
 
       def log_rate_limited(err)
+        # CLOCK_MONOTONIC counts from boot, so a numeric "never" sentinel like 0.0 would
+        # swallow the first line on a host younger than a minute (fresh CI runners are).
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        return if now - @last_log < 60
+        return if @last_log && now - @last_log < 60
 
         @last_log = now
         line = "[camada] suppressed error (SDK fails open): #{describe(err)}"

data/lib/camada/rack.rb

@@ -165,7 +165,7 @@ module Camada
         passed.on_finish&.call(500)
         raise
       end
-      headers = stamp(headers, passed)
+      headers = stamp(status, headers, passed)
       finish = passed.on_finish
       return [status, headers, body] if finish.nil?
 
@@ -176,13 +176,14 @@ module Camada
       [status, headers, proxy]
     end
 
-    # x-rid and the session cookie on the app's response. Rack 3 spells header names in lower
+    # x-rid and the session cookie on the app's response; no x-rid on a 101 (a partial-hijack
+    # websocket handshake), whose rid rides the event alone. 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)
+    def stamp(status, headers, passed)
       return headers if passed.rid.nil? && passed.set_cookie.nil?
 
       headers = headers.to_h
-      headers["x-rid"] = passed.rid if passed.rid
+      headers["x-rid"] = passed.rid if passed.rid && status.to_i != 101
       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)

data/lib/camada/snapshot/client.rb

@@ -15,7 +15,7 @@ module Camada
     #   200  [u32 LE meta-length][meta JSON][BLK container] + etag + x-camada-config
     #   304  nothing changed; config header repeated (config refreshes every poll for free)
     #   204  authenticated, no snapshot published -> enforce nothing, fail open
-    # Semantics ported exactly: single-in-flight load; loaded_at stamped even on 204 (retry per
+    # Semantics ported exactly: single-in-flight load; loaded_at stamped last, even on 204 (retry per
     # poll cadence, not per request); any error keeps the previous snapshot; cold = fail open.
     # Timers are threads here: timer mode runs one thread per client sleeping on a condition
     # variable; lazy mode kicks a one-shot thread from ensure_fresh so the request path never
@@ -153,7 +153,17 @@ module Camada
         res = @transport.call(HttpRequest.new(method: "GET", url: @url, headers: headers, body: nil, timeout_s: @timeout_s))
         return unless [200, 204, 304].include?(res.status) # 401/5xx/network: keep what we have
 
-        @loaded_at = monotonic
+        # loaded_at is stamped last (even when the body turns out corrupt): "not cold" is what Puma's
+        # request threads read as "rules in place", so it must not be visible before the matcher and
+        # config are. It is assigned after both, so a thread that sees it sees them.
+        begin
+          publish(res)
+        ensure
+          @loaded_at = monotonic
+        end
+      end
+
+      def publish(res)
         read_config(res.headers["x-camada-config"])
         return if res.status == 304
 

data/lib/camada/snapshot/match.rb

@@ -43,23 +43,6 @@ module Camada
       end
     end
 
-    def self.clean_path(raw)
-      p = raw.nil? || raw.empty? ? "/" : raw
-      q = p.index("?")
-      q.nil? ? p : p[0, q]
-    end
-
-    # Walks every '/'-terminated ancestor of `path`, the way the block side does.
-    def self.prefix_hit?(prefixes, path)
-      i = path.index("/", 1)
-      until i.nil?
-        return true if prefixes.include?(path[0, i + 1])
-
-        i = path.index("/", i + 1)
-      end
-      false
-    end
-
     # A rule decided this request (§D3): at most one of allowed / block / challenge / warn is
     # true, `reason` is 'rule', and `rule` names the id the adapters stamp on the event.
     def self.rule_result(rule, version)
@@ -89,20 +72,21 @@ module Camada
             n4 = IpParse.parse_ip4(ip)
           end
         end
+        forms = Snapshot.path_forms(i.path) # [raw, lit, full]: contracts §D3 "Path matching"
         unless s.rules.empty?
           r = RuleRequest.new(n4: n4, ip6: w, asn: i.asn, country: i.country, tlsx: i.tlsx,
-                              path: Snapshot.clean_path(i.path), ua: i.ua, header: i.header)
+                              paths: forms, ua: i.ua, header: i.header)
           s.rules.each do |rule| # the order IS the precedence (§A4): first match wins
             return Snapshot.rule_result(rule, s.version) if rule.conds.all? { |cond| cond.call(r) }
           end
         end
-        reason = side(s.allow, i, n4, w)
+        reason = side(s.allow, i, n4, w, forms, false) # an exemption: every canonical spelling must agree
         return MatchResult.new(allowed: true, reason: reason, version: s.version) if reason
 
-        reason = block_side(i, n4, w)
+        reason = block_side(i, n4, w, forms)
         return MatchResult.new(block: true, reason: reason, version: s.version) if reason
 
-        reason = side(s.challenge, i, n4, w)
+        reason = side(s.challenge, i, n4, w, forms, true)
         return MatchResult.new(challenge: true, reason: reason, version: s.version) if reason
 
         MatchResult.new(version: s.version)
@@ -178,23 +162,16 @@ module Camada
         false
       end
 
-      def blocked_path?(path)
-        s = @snap
-        return true if s.paths_exact.include?(path)
-        return true if !s.paths_prefix.empty? && Snapshot.prefix_hit?(s.paths_prefix, path)
-
-        s.paths_regex.any? { |rx| Snapshot.regex_hit?(rx, path) }
-      end
-
       # The block side: v3 sections plus the top-level meta.
-      def block_side(i, n4, w)
+      def block_side(i, n4, w, forms)
         s = @snap
         return "ip4" if n4 >= 0 && blocked4?(n4)
         return "ip6" if !w.nil? && blocked6?(w)
         return "asn" if !i.asn.nil? && blocked_asn?(i.asn)
         return "country" if Camada.present(i.country) && !s.country.empty? && s.country.include?(i.country)
         return "tls" if Camada.present(i.tlsx) && s.tls.include?(i.tlsx)
-        if (!s.paths_exact.empty? || !s.paths_prefix.empty? || !s.paths_regex.empty?) && blocked_path?(Snapshot.clean_path(i.path))
+        if (!s.paths_exact.empty? || !s.paths_prefix.empty? || !s.paths_regex.empty?) &&
+           Snapshot.path_hit?(forms, true) { |p| Snapshot.path_in?(s, p, s.paths_regex) }
           return "path"
         end
 
@@ -202,18 +179,17 @@ module Camada
       end
 
       # A v4 side list (allow or challenge). No tls axis: §A3's side meta has no tls key.
-      def side(st, i, n4, w)
+      def side(st, i, n4, w, forms, deny)
         return nil if st.empty # the common v3 snapshot
         return "ip4" if n4 >= 0 && Snapshot.in_range4?(st.r4, n4)
         return "ip6" if !w.nil? && Snapshot.in_range6?(st.r6, st.n6, w)
         return "asn" if !i.asn.nil? && st.asn.include?(i.asn)
         return "country" if Camada.present(i.country) && st.country.include?(i.country)
 
-        if !st.paths_exact.empty? || !st.paths_prefix.empty?
-          p = Snapshot.clean_path(i.path)
-          return "path" if st.paths_exact.include?(p)
-          return "path" if !st.paths_prefix.empty? && Snapshot.prefix_hit?(st.paths_prefix, p)
+        if (!st.paths_exact.empty? || !st.paths_prefix.empty?) && Snapshot.path_hit?(forms, deny) { |p| Snapshot.path_in?(st, p) }
+          return "path"
         end
+
         nil
       end
     end

data/lib/camada/snapshot/parse.rb

@@ -67,7 +67,8 @@ module Camada
 
     # 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)
+    # `paths` is the request path's [raw, lit, full] forms (Snapshot.path_forms).
+    RuleRequest = Struct.new(:n4, :ip6, :asn, :country, :tlsx, :paths, :ua, :header, keyword_init: true)
 
     CompiledRule = Struct.new(:id, :action, :conds)
 
@@ -82,8 +83,8 @@ module Camada
       m ||= {}
       asn = (m["asn"] || []).to_set(&:to_i)
       country = (m["country"] || []).to_set
-      exact = (m["pathsExact"] || []).to_set
-      prefix = (m["pathsPrefix"] || []).to_set
+      exact = (m["pathsExact"] || []).to_set { |p| canon_path(p.to_s) }
+      prefix = (m["pathsPrefix"] || []).to_set { |p| dir_key(p.to_s) }
       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
@@ -137,8 +138,8 @@ module Camada
     # 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))
+    def self.compile_regex(pattern, options = 0)
+      Regexp.new(js_to_onigmo(pattern), options)
     rescue RegexpError, TypeError, ArgumentError, EncodingError
       nil
     end
@@ -207,6 +208,122 @@ module Camada
       false
     end
 
+    # ---------- paths (contracts §D3 "Path matching") ----------
+    # A port of edge-analyst src/blocklist.js canonPath / pathForms / pathHit / pathPred. Both sides
+    # of a comparison are canonicalised so a rule catches every spelling a framework routes to the
+    # same handler: query cut at ? or #; per UTF-8 byte, %XX decoded when printable ASCII other
+    # than / and % (%2F stays %2f, one pass), every other byte written as lower-case %xx; ASCII
+    # lower-cased; each segment cut at its first ;; empty segments dropped; . and .. resolved
+    # (`full`; `lit` skips that step). A deny matches on raw, lit or full; an exemption (allow
+    # side, skip rule) needs lit AND full. Works on bytes, so a binary PATH_INFO never raises.
+    PATH_HEX = "0123456789abcdef"
+    CANON_PATH = %r{\A(?:/(?!\.\.?(?:/|\z))[a-z0-9\-._~!$&'()*+,=:@]+)+\z} # already canonical: skips the byte walk
+
+    def self.hexv(c)
+      if c.between?(48, 57) then c - 48
+      elsif c.between?(97, 102) then c - 87
+      elsif c.between?(65, 70) then c - 55
+      else -1
+      end
+    end
+
+    def self.strip_query(raw)
+      p = raw.nil? || raw.empty? ? "/" : raw
+      q = p.b.index(/[?#]/)
+      q.nil? ? p : p.byteslice(0, q)
+    end
+
+    def self.canonical?(p) = p == "/" || (p.ascii_only? && CANON_PATH.match?(p))
+
+    def self.canon_path(raw, dots: true)
+      p = strip_query(raw)
+      return p if canonical?(p)
+
+      b = p.bytes
+      s = +""
+      i = 0
+      while i < b.length
+        c = b[i]
+        decoded = c == 37 && i + 2 < b.length && hexv(b[i + 1]) >= 0 && hexv(b[i + 2]) >= 0
+        if decoded
+          c = (hexv(b[i + 1]) * 16) + hexv(b[i + 2])
+          i += 2
+        end
+        if decoded && c == 47 then s << "%2f" # a decoded %2F is never a separator
+        elsif c < 0x21 || c > 0x7e || c == 37 then s << "%" << PATH_HEX[c >> 4] << PATH_HEX[c & 15]
+        else s << (c.between?(65, 90) ? c + 32 : c).chr
+        end
+        i += 1
+      end
+      out = []
+      s.split("/").each do |seg|
+        k = seg.index(";")
+        seg = seg[0, k] unless k.nil?
+        next if seg.empty? || (dots && seg == ".")
+
+        if dots && seg == ".."
+          out.pop
+          next
+        end
+        out << seg
+      end
+      "/#{out.join("/")}"
+    end
+
+    # [raw (query cut), lit, full] for one request path.
+    def self.path_forms(raw)
+      p = strip_query(raw)
+      return [p, p, p] if canonical?(p)
+
+      [p, canon_path(p, dots: false), canon_path(p)]
+    end
+
+    def self.path_dir(p) = p.end_with?("/") ? p : "#{p}/"
+
+    # A prefix entry or a starts_with value ending in / -> its canonical directory key ('/' stays '/').
+    def self.dir_key(v) = path_dir(canon_path(v))
+
+    # Walks '/' boundaries: /a/b tries /, /a/, /a/b/.
+    def self.prefix_hit?(prefixes, path)
+      d = path_dir(path).b
+      i = 0
+      until i.nil?
+        return true if prefixes.include?(d.byteslice(0, i + 1))
+
+        i = d.index("/", i + 1)
+      end
+      false
+    end
+
+    # One path form against a side's (or the block side's) exact, prefix and regex entries.
+    def self.path_in?(st, path, regexes = [])
+      return true if st.paths_exact.include?(path)
+      return true if !st.paths_prefix.empty? && prefix_hit?(st.paths_prefix, path)
+
+      regexes.any? { |rx| regex_hit?(rx, path) }
+    end
+
+    # Does the block hold for this request's path? deny = any spelling; an exemption = both canonical forms.
+    def self.path_hit?(forms, deny, &pred)
+      deny ? (pred.call(forms[0]) || pred.call(forms[1]) || pred.call(forms[2])) : (pred.call(forms[1]) && pred.call(forms[2]))
+    end
+
+    # One path condition -> a predicate over a single path form.
+    def self.path_pred(op, values)
+      case op
+      when "matches"
+        rx = compile_regex(values[0], Regexp::IGNORECASE)
+        ->(p) { !rx.nil? && regex_hit?(rx, p) }
+      when "starts_with"
+        v = values[0]
+        key = v.end_with?("/") ? dir_key(v) : canon_path(v)
+        ->(p) { text_hit? { path_dir(p).start_with?(key) } }
+      else
+        set = values.to_set { |v| canon_path(v) }
+        ->(p) { set.include?(p) }
+      end
+    end
+
     # ---------- custom rules (v5) ----------
 
     # The string one condition reads, or nil when this request cannot answer the field.
@@ -216,7 +333,6 @@ module Camada
       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
@@ -224,9 +340,14 @@ module Camada
 
     # 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)
+    def self.compile_cond(c, sets, deny = true)
       f = c["f"].to_s
       op = c["op"].to_s
+      if f == "path" # every path op reads the canonical forms (see "paths" above)
+        raw = c["v"]
+        pred = path_pred(op, raw.is_a?(Array) ? raw.map(&:to_s) : [raw.to_s])
+        return ->(r) { path_hit?(r.paths, deny, &pred) }
+      end
       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
@@ -306,7 +427,7 @@ module Camada
           [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) }
+          (r["conds"] || []).map { |c| compile_cond(c, sets, action != "skip") }
         rescue StandardError
           next # a malformed rule is dropped, never enforced
         end
@@ -351,9 +472,9 @@ module Camada
         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) },
+        paths_exact: (meta["pathsExact"] || []).to_set { |p| canon_path(p.to_s) },
+        paths_prefix: (meta["pathsPrefix"] || []).to_set { |p| dir_key(p.to_s) },
+        paths_regex: (meta["pathsRegex"] || []).filter_map { |p| compile_regex(p, Regexp::IGNORECASE) },
         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)

data/lib/camada/version.rb

@@ -5,6 +5,6 @@ module Camada
   # 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"
+  VERSION = "0.1.2"
   SDK_ID = "@camada/ruby/#{VERSION}".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: camada
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - camada
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-10-04 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,