zeroclick-sellers 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6127c1b9413ac6cbf8d9690e972e319418e2bee6ba3a025ba057c6752d04a370
-  data.tar.gz: 384bfdd1ba3393497943aa9c37138f0b9fae69098a2404b3dfd6b2e51f61493b
+  metadata.gz: 2865ea4c52917887161bb00e22f46bdd275f28a6a7ac3a2e72d680b3db32323c
+  data.tar.gz: 4ca1a1c4665a099a54e15fb459a36eaa951feb718331fa6303cd4e81b2356d22
 SHA512:
-  metadata.gz: 446af6c8cb1563130c222f09ec8ee8eeb4308636782925acd269d7353a1ed3cbc52f7aa8ac033fb0a1eb6bb4fe268b2d5178a5b483e7e7cf9348c18ea291a99d
-  data.tar.gz: 40f965870f70c61902865c586d930c39f4c1165a943244dfc6647d05abdbc93bb2faf65f184188cc80e03e45a860b5c410c5db8d2c97f48545206a5a663657cc
+  metadata.gz: 1b9b122f2cea8b056f79fe2aa56af4d674818148ae8e6b60adb4ac9b000520f06d360c22980c0c6900e87bc02882218d1e9e4815248b8d65d5319608e1a4d0a4
+  data.tar.gz: 81c0463cda57c90787550a9215a786d41d555486eaef5af19f081b965af84608d87819f2f053be1195425e815aa985d777761897090049bbced8dcb74981e73c

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,14 @@ 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;
+      #   - the visitor's country rides along when the edge resolved it: the
+      #     header Cloudflare, CloudFront, Vercel or App Engine sets, or
+      #     +resolve_country+; a host whose edge sets none sends no country;
+      #   - 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 +51,27 @@ 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-"
+
+        # The vendor request headers (as Rack env keys) that carry the
+        # visitor's country as the edge resolved it, outermost layer first: a
+        # CDN in front of a platform sees the true client, while the platform
+        # behind it geolocates the CDN's edge, so the outer header wins when
+        # both are present. Each is the vendor's documented header, forwarded
+        # raw; the API clamps it to a 2-letter code and drops the vendors'
+        # unknown sentinels (Cloudflare XX, App Engine ZZ).
+        COUNTRY_HEADERS = %w[
+          HTTP_CF_IPCOUNTRY
+          HTTP_CLOUDFRONT_VIEWER_COUNTRY
+          HTTP_X_VERCEL_IP_COUNTRY
+          HTTP_X_APPENGINE_COUNTRY
+        ].freeze
+
         # +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,15 +80,21 @@ 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
-        # path; it is never re-raised.
-        def initialize(app, seller_id:, seller: nil, clock: nil, resolve_url: nil, on_error: nil)
+        # 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. +resolve_country+ is a callable taking
+        # the Rack env and returning the visitor's country, replacing the
+        # vendor-header read (COUNTRY_HEADERS) with the seller's own source:
+        # exactly one header, or a runtime that exposes the country another
+        # way. Return nil for unknown.
+        def initialize(app, seller_id:, seller: nil, clock: nil, resolve_url: nil, on_error: nil, resolve_country: nil)
           @app = app
           @seller_source = seller
           @seller_id = seller_id
           @clock = clock || DEFAULT_CLOCK
           @resolve_url = resolve_url
           @on_error = on_error
+          @resolve_country = resolve_country
         end
 
         def call(env)
@@ -86,7 +121,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)
 
@@ -100,12 +136,69 @@ module ZeroClick
             user_agent: env["HTTP_USER_AGENT"],
             accept: env["HTTP_ACCEPT"],
             client_ip: client_ip_of(env),
-            country: env["HTTP_CF_IPCOUNTRY"],
+            country: country_of(env),
             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.
@@ -134,6 +227,20 @@ module ZeroClick
           first.empty? ? nil : first
         end
 
+        # The visitor's country as the edge resolved it: the first present of
+        # COUNTRY_HEADERS, or whatever +resolve_country+ returns. nil when the
+        # edge set none of them, so a host without one sends no country rather
+        # than a guess; an empty value is left out the same way.
+        def country_of(env)
+          value = if @resolve_country
+                    @resolve_country.call(env)
+                  else
+                    COUNTRY_HEADERS.lazy.map { |key| env[key] }.find { |v| v && !v.strip.empty? }
+                  end
+          value = value&.strip
+          value.nil? || value.empty? ? nil : value
+        end
+
         # The referrer reduced to its host at the edge, so the full referrer
         # (its path and query, which can carry identifying values) never leaves
         # the site. A malformed referrer yields no host rather than the full URL.
@@ -146,11 +253,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.8.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.8.0
 platform: ruby
 authors:
 - ZeroClick
@@ -15,7 +15,7 @@ description: |
   and report what was used. Ships Rack middleware, so it works in Rails,
   Sinatra, Hanami and Roda alike.
 email:
-- support@zeroclick.ai
+- help@zeroclick.ai
 executables: []
 extensions: []
 extra_rdoc_files: []