zeroclick-sellers 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6127c1b9413ac6cbf8d9690e972e319418e2bee6ba3a025ba057c6752d04a370
-  data.tar.gz: 384bfdd1ba3393497943aa9c37138f0b9fae69098a2404b3dfd6b2e51f61493b
+  metadata.gz: 27bd4f5d8f10f026b12a89ee8681fef45ffbf58129df180f40903a55ec9743d3
+  data.tar.gz: 1ea73b94f08215d28c2974ac4937bdc423aa2f52a66c688a5746656ad837c8f2
 SHA512:
-  metadata.gz: 446af6c8cb1563130c222f09ec8ee8eeb4308636782925acd269d7353a1ed3cbc52f7aa8ac033fb0a1eb6bb4fe268b2d5178a5b483e7e7cf9348c18ea291a99d
-  data.tar.gz: 40f965870f70c61902865c586d930c39f4c1165a943244dfc6647d05abdbc93bb2faf65f184188cc80e03e45a860b5c410c5db8d2c97f48545206a5a663657cc
+  metadata.gz: 73ef4fc05515a9d11212ca90c7df1c9f97c157bdc2628c4b1bb81738849552fbd7aca334986fc60f1c4d0d5cb6ca311b7663c453c1633a756950e82af4f06b42
+  data.tar.gz: 00dbf768601b7808759518ad6a507e0d238f4c6c65aecdd91ce5106488841a19538f5ea49ea5df93e776a049330f32f834d7d9216dd0ce58b212bf6da24e1748

data/lib/zeroclick/sellers/client.rb

@@ -191,7 +191,9 @@ module ZeroClick
       # +seller+ is the seller's public id; +path+ must be an absolute path.
       def report_page_view(seller:, path:, status: nil, duration_ms: nil, representation: nil,
                            journey_id: nil, captured_at: nil, user_agent: nil, accept: nil,
-                           client_ip: nil, country: nil, referrer_host: nil)
+                           client_ip: nil, country: nil, referrer_host: nil, host: nil,
+                           eval_tag: nil, eval_signature: nil, eval_signature_input: nil,
+                           eval_signature_agent: nil, source: nil, source_signature: nil)
         if @page_views_key.nil? || @page_views_key.empty?
           raise Error.new("page_views_not_configured", operation: "report_page_view")
         end
@@ -200,7 +202,10 @@ module ZeroClick
           seller: seller, path: path, status: status, duration_ms: duration_ms,
           representation: representation, journey_id: journey_id, captured_at: captured_at,
           user_agent: user_agent, accept: accept, client_ip: client_ip,
-          country: country, referrer_host: referrer_host
+          country: country, referrer_host: referrer_host, host: host,
+          eval_tag: eval_tag, eval_signature: eval_signature,
+          eval_signature_input: eval_signature_input, eval_signature_agent: eval_signature_agent,
+          source: source, source_signature: source_signature
         )
         status_code, body = @http_post.call(
           base_url: @api_base_url,

data/lib/zeroclick/sellers/middleware/page_views.rb

@@ -22,6 +22,11 @@ module ZeroClick
       #   - the app runs FIRST, so the beacon carries the real status and
       #     duration; the visitor's user-agent, accept, and connecting IP are
       #     forwarded for server-side classification;
+      #   - a ZeroClick agent-eval request's tag and signature are forwarded
+      #     with the page's host, so the API can keep ZeroClick's own eval
+      #     traffic out of the seller's numbers; a browser-based run, which
+      #     cannot sign, is told by the +src+ marker on its start URL,
+      #     forwarded with the host and the signature beside it;
       #   - ANY beacon failure — missing key, network error, non-204, timeout,
       #     a bad resolve_url or clock — is handed to +on_error+ and swallowed.
       #     The middleware must never break or alter the customer's site.
@@ -43,6 +48,13 @@ module ZeroClick
         # duration. Injectable so a test can make both deterministic.
         DEFAULT_CLOCK = -> { Process.clock_gettime(Process::CLOCK_REALTIME, :float_millisecond) }
 
+        # ZeroClick's own start marker: the one query value the middleware
+        # forwards. A browser-based eval run's requests leave from the agent
+        # vendor's cloud, out of reach of the signed tag, so agent-eval marks
+        # its start URL as ?src=ze-<experiment>-<n> instead, and the API keeps
+        # the whole visit out of the seller's numbers from it.
+        EVAL_SOURCE_PREFIX = "ze-"
+
         # +seller+ may be a client, a callable returning one, or omitted to
         # resolve the process-wide ZeroClick::Sellers.seller on the first
         # request (the Rails path — see Base#initialize for why).
@@ -51,7 +63,8 @@ module ZeroClick
         # by the wire contract). +clock+ returns epoch milliseconds.
         # +resolve_url+ is a callable taking the Rack env and returning the
         # public URL of the request, for servers behind a proxy that rewrites
-        # the host the runtime sees. +on_error+ observes the fire-and-forget
+        # the host the runtime sees; its path is reported and, with an eval
+        # tag, its host. +on_error+ observes the fire-and-forget
         # path; it is never re-raised.
         def initialize(app, seller_id:, seller: nil, clock: nil, resolve_url: nil, on_error: nil)
           @app = app
@@ -86,7 +99,8 @@ module ZeroClick
           return unless env["REQUEST_METHOD"] == "GET"
 
           url = @resolve_url ? @resolve_url.call(env) : Agentify.public_url(env)
-          path = URI.parse(url.to_s).path
+          uri = URI.parse(url.to_s)
+          path = uri.path
           path = "/" if path.nil? || path.empty?
           return if ASSET_PATH.match?(path)
 
@@ -102,10 +116,67 @@ module ZeroClick
             client_ip: client_ip_of(env),
             country: env["HTTP_CF_IPCOUNTRY"],
             referrer_host: referrer_host_of(env),
-            journey_id: journey_id_of(headers)
+            journey_id: journey_id_of(headers),
+            **start_marker_of(uri),
+            **eval_run_of(env, uri)
           )
         end
 
+        # ZeroClick's own agent-eval run, when the visitor carried its tag: the
+        # tag, the signature agent-eval puts on a seller's site (under
+        # ZeroClick-only header names, never Web Bot Auth's) and the public
+        # host it was signed for. Forwarded as sent; the API labels the view
+        # only when the signature verifies, so a forged tag labels nothing. A
+        # value outside what the beacon accepts (empty, or longer than
+        # agent-eval ever sends) is left out rather than sent, so a visitor's
+        # odd header can never cost the page view itself.
+        def eval_run_of(env, uri)
+          tag = capped(env["HTTP_X_ZEROCLICK_EVAL"], 512)
+          return {} if tag.nil?
+
+          {
+            host: capped(host_of(uri), 300),
+            eval_tag: tag,
+            eval_signature: capped(env["HTTP_X_ZEROCLICK_EVAL_SIGNATURE"], 1_024),
+            eval_signature_input: capped(env["HTTP_X_ZEROCLICK_EVAL_SIGNATURE_INPUT"], 1_024),
+            eval_signature_agent: capped(env["HTTP_X_ZEROCLICK_EVAL_SIGNATURE_AGENT"], 512)
+          }
+        end
+
+        def capped(value, max)
+          value && !value.empty? && value.length <= max ? value : nil
+        end
+
+        # The public host the page was requested on, as the JS SDK's URL.host
+        # reads it: the host and any non-default port.
+        def host_of(uri)
+          return nil if uri.host.nil? || uri.host.empty?
+
+          uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        end
+
+        # ZeroClick's own start marker, keyed like report_page_view: empty
+        # without one. The +src+ query value when it is ours, the page's host
+        # and the +signature+ agent-eval puts beside the marker, as sent: the
+        # only query values the beacon carries. Any other +src+ stays on the
+        # site, and a marker or signature past what the beacon accepts (or a
+        # query that does not decode) is left out rather than sent.
+        def start_marker_of(uri)
+          return {} if uri.query.nil? || uri.query.empty?
+
+          values = URI.decode_www_form(uri.query)
+          src = values.assoc("src")&.last
+          return {} unless src&.start_with?(EVAL_SOURCE_PREFIX) && src.length <= 32
+
+          {
+            host: capped(host_of(uri), 300),
+            source: src,
+            source_signature: capped(values.assoc("signature")&.last, 256)
+          }
+        rescue ArgumentError
+          {}
+        end
+
         # What the app served for this page-content request, read off the
         # response content-type so it reflects the real representation
         # regardless of what produced it.
@@ -146,11 +217,7 @@ module ZeroClick
           rescue URI::InvalidURIError
             nil
           end
-          host = uri&.host
-          return nil if host.nil? || host.empty?
-
-          # Host and any non-default port only, matching the JS SDK's URL.host.
-          uri.port && uri.port != uri.default_port ? "#{host}:#{uri.port}" : host
+          uri && host_of(uri)
         end
 
         # Case-insensitive lookup over the app's response headers.

data/lib/zeroclick/sellers/page_views.rb

@@ -27,9 +27,15 @@ module ZeroClick
       # Build the wire body: camelCase string keys, every absent optional key
       # omitted. +seller+ is the seller's public id and +path+ must be an
       # absolute path, both rejected before any request leaves the process.
+      # +host+ and the +eval_*+ values describe ZeroClick's own agent-eval run
+      # when the visitor carried its tag: the public host the run signed for
+      # and the tag with its signature, as sent. The API labels the view as
+      # eval traffic only when the signature verifies.
       def build_payload(seller:, path:, status: nil, duration_ms: nil, representation: nil,
                         journey_id: nil, captured_at: nil, user_agent: nil, accept: nil,
-                        client_ip: nil, country: nil, referrer_host: nil)
+                        client_ip: nil, country: nil, referrer_host: nil, host: nil,
+                        eval_tag: nil, eval_signature: nil, eval_signature_input: nil,
+                        eval_signature_agent: nil, source: nil, source_signature: nil)
         Sellers.require_slug!(seller, "seller", "report_page_view")
         unless path.is_a?(String) && path.start_with?("/")
           raise Error.new("malformed_input", operation: "report_page_view",
@@ -51,6 +57,13 @@ module ZeroClick
         payload["clientIp"] = client_ip unless client_ip.nil?
         payload["country"] = country unless country.nil?
         payload["referrerHost"] = referrer_host unless referrer_host.nil?
+        payload["host"] = host unless host.nil?
+        payload["evalTag"] = eval_tag unless eval_tag.nil?
+        payload["evalSignature"] = eval_signature unless eval_signature.nil?
+        payload["evalSignatureInput"] = eval_signature_input unless eval_signature_input.nil?
+        payload["evalSignatureAgent"] = eval_signature_agent unless eval_signature_agent.nil?
+        payload["source"] = source unless source.nil?
+        payload["sourceSignature"] = source_signature unless source_signature.nil?
         payload
       end
 

data/lib/zeroclick/sellers/version.rb

@@ -4,6 +4,6 @@ module ZeroClick
   module Sellers
     # Bump this to publish. The workflow reads it, asks RubyGems whether this
     # version already exists, and publishes only when it does not.
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zeroclick-sellers
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ZeroClick