track_relay 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 918577fceae3974911227a1b988f8d17ecf636c086b7f91ad9b8e36ac6d2b9fd
-  data.tar.gz: 1dcd1c4f9bb900b0b3945a40ae0222b3205212f52477e10640baa0facc39ae40
+  metadata.gz: aaa3f984be840d9f657d23e543aae04eccac6c45da4877fcdaad30e8f3dc7f7a
+  data.tar.gz: ed659de0a4cd9e7a63d50d8d6ddeb32c962c667471e4c9b56f143fcf16f0b26b
 SHA512:
-  metadata.gz: c95d0181afcad7811afaff649155f78681f41a2d54fc3f3ebaf1057f56e4b146d5704a6954e83183d9ef78269a807b648545cc493b42e22c9b93dd53084c9fd2
-  data.tar.gz: 9d0c93c207fbdfa07237d9f25657053626711ac0eedf576fd0bb36db84203b67e716bd0f382face10074cbacb4a24842a7e56ac1c7b7adc82ac59aed66036fd3
+  metadata.gz: 19dd615e0a99f54df3bedaf1eb01b61ace7a338fa04d4d77373cbb43b9e786e221ade99ea3fd52e13b82a64be705a5ec2674bdc3fb69223d84e2b25157da272b
+  data.tar.gz: eabf9d5db4cb4da4643815b628cc7c065b6b93b4f4ad8345b2d4525a93c6ea982f7877db25fae2df294bef512a222cdfb3b25966988bd5f13f9e54ad58b70646

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-07-31
+
+### Added
+- `ClientId::SignedToken` — first-party, HMAC-signed analytics token
+  (ActiveSupport::MessageVerifier, SHA256) as a cryptographic
+  proof-of-browser replacement for `_ga`-cookie sniffing. Carries
+  `client_id`, `session_id`, `session_started_at`, and `last_seen_at`;
+  `mint`/`read`/`from_request` reject tampered, forged, wrong-secret,
+  and expired (`ttl:`) values by returning `nil`.
+- `TrackRelay::HandshakeEndpoint` — routable Rack endpoint
+  (`post "/analytics/handshakes", to: TrackRelay::HandshakeEndpoint`)
+  that mints/refreshes the signed token cookie (HttpOnly,
+  SameSite=Lax, secure on SSL). Preserves an existing token's
+  client_id, rotates the session after 30 minutes of inactivity
+  (`SESSION_INACTIVITY_TIMEOUT`), and raises `ConfigurationError`
+  when `signed_client_token_secret` is unset.
+- Config: `signed_client_token_secret` (default `nil` — feature off)
+  and `signed_client_token_ttl` (default 30 days).
+- `ConfigurationError` error class.
+
+### Changed
+- `Subscribers::Ga4MeasurementProtocol#prepare` now prefers the signed
+  first-party token — for both the browser-proof client_id and
+  page-context session enrichment — falling back to the `_ga` /
+  `_ga_<stream>` cookies so hosts can migrate incrementally. Behavior
+  is unchanged for hosts that don't configure a signed-token secret.
+
 ## [1.1.0] - 2026-07-07
 
 ### Added

data/lib/track_relay/client_id/signed_token.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "active_support/message_verifier"
+
+module TrackRelay
+  module ClientId
+    # First-party, HMAC-signed client token — the spoof-proof
+    # replacement for `_ga`-cookie browser proof.
+    #
+    # The cookie value is generated and verified with
+    # {ActiveSupport::MessageVerifier} (SHA256), so any tampering,
+    # truncation, or wrong-secret forgery verifies to `nil` rather
+    # than raising.
+    class SignedToken
+      COOKIE_NAME = "_tr_cid"
+
+      # Verified token contents. `session_started_at` is a Time (UTC);
+      # `session_id`/`client_id` are strings shaped for GA4 payloads.
+      Token = Struct.new(:client_id, :session_id, :session_started_at, :last_seen_at, keyword_init: true)
+
+      # Generate a signed cookie value embedding the client_id and
+      # optional session fields.
+      #
+      # @param secret [String] HMAC signing secret
+      # @param client_id [String] GA4-shaped client id to embed
+      # @param session_id [String, nil] GA4 session id
+      # @param session_started_at [Time, nil] start of the embedded session
+      # @param ttl [ActiveSupport::Duration, nil] validity window;
+      #   `nil` mints a non-expiring token
+      # @return [String] opaque signed cookie value
+      def self.mint(secret:, client_id:, session_id: nil, session_started_at: nil, last_seen_at: nil, ttl: nil)
+        payload = {
+          "cid" => client_id,
+          "sid" => session_id,
+          "sst" => session_started_at&.to_i,
+          "lsa" => last_seen_at&.to_i
+        }.compact
+        verifier(secret).generate(payload, expires_in: ttl)
+      end
+
+      # Read and verify the signed cookie into a {Token}.
+      #
+      # @param request [#cookies, nil] any object exposing
+      #   `request.cookies[COOKIE_NAME]`
+      # @param secret [String] HMAC signing secret
+      # @return [Token, nil] verified token contents, or `nil` when the
+      #   cookie is missing or unverifiable.
+      def self.read(request, secret:)
+        value = request&.cookies&.[](COOKIE_NAME)
+        return nil if value.nil? || value.empty?
+
+        payload = verifier(secret).verified(value)
+        return nil unless payload
+
+        Token.new(
+          client_id: payload["cid"],
+          session_id: payload["sid"],
+          session_started_at: payload["sst"] && Time.at(payload["sst"]).utc,
+          last_seen_at: payload["lsa"] && Time.at(payload["lsa"]).utc
+        )
+      end
+
+      # Convenience for gate/client-id use: just the verified client_id.
+      #
+      # @param request [#cookies, nil] any object exposing
+      #   `request.cookies[COOKIE_NAME]`
+      # @param secret [String] HMAC signing secret
+      # @return [String, nil] the embedded client_id, or `nil` when the
+      #   cookie is missing or unverifiable.
+      def self.from_request(request, secret:)
+        read(request, secret: secret)&.client_id
+      end
+
+      def self.verifier(secret)
+        ActiveSupport::MessageVerifier.new(secret, digest: "SHA256", serializer: JSON)
+      end
+      private_class_method :verifier
+    end
+  end
+end

data/lib/track_relay/configuration.rb

@@ -85,7 +85,9 @@ module TrackRelay
       :ga4_use_eu_endpoint,
       :ga4_require_browser_client_id,
       :ga4_enrich_page_context,
-      :track_gate
+      :track_gate,
+      :signed_client_token_secret,
+      :signed_client_token_ttl
 
     # @return [Array] registered subscriber instances, in insertion order
     attr_reader :subscribers
@@ -112,6 +114,8 @@ module TrackRelay
       @ga4_require_browser_client_id = false
       @ga4_enrich_page_context = false
       @track_gate = nil
+      @signed_client_token_secret = nil
+      @signed_client_token_ttl = 30.days
     end
 
     # Append a subscriber to the registry.

data/lib/track_relay/errors.rb

@@ -32,6 +32,11 @@ module TrackRelay
   # the catalog and untyped events are disabled.
   class UnknownEventError < Error; end
 
+  # Raised when a feature is used without its required configuration —
+  # e.g. mounting {HandshakeEndpoint} without setting
+  # `config.signed_client_token_secret`.
+  class ConfigurationError < Error; end
+
   # Raised by a subscriber's `#deliver` to signal a *transient* failure
   # that the {DeliveryJob} should retry via ActiveJob's `retry_on`.
   # Examples: HTTP 5xx response, `Net::OpenTimeout`, `Errno::ECONNREFUSED`,

data/lib/track_relay/handshake_endpoint.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TrackRelay
+  # Routable Rack endpoint that mints the first-party signed analytics
+  # token ({ClientId::SignedToken}). Hosts mount it directly:
+  #
+  #   post "/analytics/handshakes", to: TrackRelay::HandshakeEndpoint
+  #
+  # A small host-side JS module calls it from the browser; because only
+  # JS-executing clients ever do, possession of a valid token is
+  # proof-of-browser for the host's `track_gate`.
+  class HandshakeEndpoint
+    # GA4 semantics: a session ends after this much inactivity, however
+    # long it has been running. Activity = any handshake call.
+    SESSION_INACTIVITY_TIMEOUT = 30 * 60
+
+    def self.call(env)
+      new.call(env)
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      config = TrackRelay.config
+      now = Time.now.utc
+
+      if config.signed_client_token_secret.nil? || config.signed_client_token_secret.empty?
+        raise ConfigurationError,
+          "TrackRelay::HandshakeEndpoint requires config.signed_client_token_secret to be set"
+      end
+
+      existing = ClientId::SignedToken.read(request, secret: config.signed_client_token_secret)
+      session_alive = existing && !session_stale?(existing, now)
+
+      cookie_value = ClientId::SignedToken.mint(
+        secret: config.signed_client_token_secret,
+        client_id: existing&.client_id || fresh_client_id(now),
+        session_id: session_alive ? existing.session_id : now.to_i.to_s,
+        session_started_at: session_alive ? existing.session_started_at : now,
+        last_seen_at: now,
+        ttl: config.signed_client_token_ttl
+      )
+
+      [204, {"set-cookie" => set_cookie(cookie_value, request, now, config)}, []]
+    end
+
+    private
+
+    # A session with no recorded activity falls back to its start time,
+    # so pre-`last_seen_at` tokens still rotate sensibly.
+    def session_stale?(token, now)
+      reference = token.last_seen_at || token.session_started_at
+      reference.nil? || (now - reference) > SESSION_INACTIVITY_TIMEOUT
+    end
+
+    # GA4-shaped client_id: `<random_int31>.<unix_ts>`.
+    def fresh_client_id(now)
+      "#{SecureRandom.random_number(0x7FFFFFFF)}.#{now.to_i}"
+    end
+
+    def set_cookie(value, request, now, config)
+      attributes = {
+        value: value,
+        path: "/",
+        httponly: true,
+        same_site: :lax,
+        secure: request.ssl?
+      }
+      attributes[:expires] = now + config.signed_client_token_ttl if config.signed_client_token_ttl
+
+      Rack::Utils.set_cookie_header(ClientId::SignedToken::COOKIE_NAME, attributes)
+    end
+  end
+end

data/lib/track_relay/subscribers/ga4_measurement_protocol.rb

@@ -121,12 +121,13 @@ module TrackRelay
         return payload unless config.ga4_require_browser_client_id || config.ga4_enrich_page_context
 
         request = Current.request
-        client_id = ClientId::Ga.from_request(request)
+        token = signed_token(request, config)
+        client_id = token&.client_id || ClientId::Ga.from_request(request)
         return nil if config.ga4_require_browser_client_id && client_id.nil?
         return payload if request.nil?
 
         hash = payload.to_h
-        hash[:params] = hash[:params].merge(page_params(request)) if config.ga4_enrich_page_context
+        hash[:params] = hash[:params].merge(page_params(request, token)) if config.ga4_enrich_page_context
         hash[:context] = hash[:context].merge(client_id: client_id) if client_id
         EventPayload.from_h(hash)
       end
@@ -158,13 +159,25 @@ module TrackRelay
 
       private
 
+      # Verified first-party token, when the host has configured a
+      # signed-token secret. The token is the preferred (cryptographic)
+      # source for both client_id and session_id; the `_ga`/`_ga_<stream>`
+      # cookies remain as fallbacks so hosts can migrate incrementally.
+      #
+      # @return [ClientId::SignedToken::Token, nil]
+      def signed_token(request, config)
+        return nil unless config.signed_client_token_secret
+
+        ClientId::SignedToken.read(request, secret: config.signed_client_token_secret)
+      end
+
       # Page-context params captured from the live request (only when
       # `config.ga4_enrich_page_context` is enabled).
-      def page_params(request)
+      def page_params(request, token = nil)
         params = {page_location: request.original_url}
         params[:page_referrer] = request.referer if request.referer && !request.referer.empty?
 
-        if (session_id = ga_session_id(request))
+        if (session_id = token&.session_id || ga_session_id(request))
           params[:session_id] = session_id
           params[:engagement_time_msec] = ENGAGEMENT_TIME_MSEC
         end

data/lib/track_relay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TrackRelay
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/track_relay.rb

@@ -12,6 +12,8 @@ require "track_relay/current"
 require "track_relay/client_id/ga"
 require "track_relay/client_id/ahoy_visitor"
 require "track_relay/client_id/session"
+require "track_relay/client_id/signed_token"
+require "track_relay/handshake_endpoint"
 require "track_relay/configuration"
 require "track_relay/instrumenter"
 require "track_relay/subscribers/base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: track_relay
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - dchuk
@@ -193,6 +193,7 @@ files:
 - lib/track_relay/client_id/ahoy_visitor.rb
 - lib/track_relay/client_id/ga.rb
 - lib/track_relay/client_id/session.rb
+- lib/track_relay/client_id/signed_token.rb
 - lib/track_relay/configuration.rb
 - lib/track_relay/controller_tracking.rb
 - lib/track_relay/current.rb
@@ -203,6 +204,7 @@ files:
 - lib/track_relay/errors.rb
 - lib/track_relay/event_definition.rb
 - lib/track_relay/event_payload.rb
+- lib/track_relay/handshake_endpoint.rb
 - lib/track_relay/instrumenter.rb
 - lib/track_relay/job_tracking.rb
 - lib/track_relay/linter.rb