trackguard 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 316a34bc16b1eb01f85bf67eb0590083bb785e3fc7ec33c155c88f710598bff8
-  data.tar.gz: 274cb339c6c5b66bb6a806eadf2c85c2b6e17a571e5a6afd7b0add98ab318b2f
+  metadata.gz: c2629b3c673c2ac2c1f4e338dedc3abc7f9b572fb57e9b4f9091139809e362bc
+  data.tar.gz: 6b4657343eecf9de2b48bea0df3f24c4463109dc6ae521dc83dad79741bbfe99
 SHA512:
-  metadata.gz: 44e7c8a7af2af602c82b0deccee434b1f648669436191cd2d912445deaf4d5b1b8164e2129cb70b88fe60d626034825823decb3a020148b25a954a76a53e2158
-  data.tar.gz: 808ada400efdf41eb5861ef9218f8cef8e90032ab8cda97b38b9492347d1ab96b4f558f1079c20767e711369e2c28ae62fe91028022cb36f2484efd9ca9c524a
+  metadata.gz: d8b5fc84be6801c276f5d7cb7dd0007a7b1c7d5d19d5db9858f2412396e3c99fc604e9276cc34ee0a05b4b63cc01f72fac8e176b1c2e852405813e0e484b4733
+  data.tar.gz: 96c791bce0d1cd72230e89e34a6335e4c7dfdbe818f90dccbd466bb3e908c2b9437e820dfe6afb9ced8a605e5293f341c65dd541e603a8bd9594210009c4dfe8

data/app/assets/javascripts/controllers/page_tracker_controller.js

@@ -11,8 +11,7 @@ export default class extends Controller {
     window.addEventListener("hashchange", this.boundHash)
 
     // Cover initial load if turbo:load already fired before connect()
-    // Pass initial=true so the job can deduplicate/enrich against the server-side record
-    this.trackCurrent(true)
+    this.trackCurrent()
   }
 
   disconnect() {
@@ -20,14 +19,14 @@ export default class extends Controller {
     window.removeEventListener("hashchange", this.boundHash)
   }
 
-  trackCurrent(initial = false) {
+  trackCurrent() {
     const path = window.location.pathname + window.location.hash
     if (path === this.lastTracked) return
     this.lastTracked = path
-    this.track(path, initial)
+    this.track(path)
   }
 
-  track(path, initial = false) {
+  track(path) {
     const token = document.querySelector('meta[name="csrf-token"]')?.content
     const traceId = document.querySelector('meta[name="trace-id"]')?.content
     const url = this.urlValue || document.querySelector('meta[name="trackguard-url"]')?.content
@@ -35,7 +34,7 @@ export default class extends Controller {
     fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json", "X-CSRF-Token": token || "" },
-      body: JSON.stringify({ path, trace_id: traceId, ref, initial })
+      body: JSON.stringify({ path, trace_id: traceId, ref })
     })
   }
 }

data/app/assets/stylesheets/trackguard/admin.css

@@ -291,6 +291,10 @@
   background: rgba(239, 68, 68, 0.05);
 }
 
+.tg-row--suspicious {
+  background: rgba(251, 191, 36, 0.1);
+}
+
 .tg-row--whitelisted {
   background: rgba(34, 197, 94, 0.05);
 }
@@ -352,6 +356,14 @@
   font-size: 0.875rem;
 }
 
+.tg-summary__layer {
+  width: 2.5rem;
+  text-align: center;
+  flex-shrink: 0;
+  color: #d1d5db;
+  font-size: 0.875rem;
+}
+
 .tg-summary__time {
   font-size: 0.8125rem;
   color: #9ca3af;
@@ -366,6 +378,13 @@
   vertical-align: middle;
 }
 
+.tg-suspicious-icon {
+  width: 1rem;
+  height: 1rem;
+  color: #f59e0b;
+  vertical-align: middle;
+}
+
 .tg-whitelist-icon {
   width: 1rem;
   height: 1rem;
@@ -373,6 +392,27 @@
   vertical-align: middle;
 }
 
+.tg-layer-badge {
+  display: inline-block;
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  border-radius: 3px;
+  padding: 0.125rem 0.3rem;
+  line-height: 1.4;
+}
+
+.tg-layer-badge--js {
+  background: #d1fae5;
+  color: #065f46;
+}
+
+.tg-layer-badge--backend {
+  background: #ffedd5;
+  color: #c2410c;
+}
+
 /* ── Detail panel ──────────────────────────────────────────────────── */
 .tg-detail {
   padding: 0 1rem 1rem 1rem;
@@ -428,6 +468,8 @@
 
 .tg-dl__def--flagged { color: #dc2626; }
 
+.tg-dl__def--suspicious { color: #d97706; }
+
 .tg-dl__def--muted { color: #9ca3af; }
 
 .tg-dl__def--whitelisted { color: #059669; }

data/app/controllers/concerns/trackguard/page_tracker.rb

@@ -30,7 +30,7 @@ module Trackguard
         session_id: session.id.to_s,
         trace_id: @trace_id,
         source: extract_source,
-        initial: false,
+        tracking_layer: "backend",
         http_method: request.request_method
       )
     end

data/app/controllers/trackguard/admin/analytics_controller.rb

@@ -64,6 +64,7 @@ module Trackguard
         {
           path: view.path,
           ip: view.visitor&.ip,
+          suspicious_state: view.visitor.suspicious_state,
           flagged_at: view.visitor.flagged_at,
           flagged_by: view.visitor.flagged_by,
           whitelisted: view.visitor.whitelisted_ip&.active? || false,

data/app/controllers/trackguard/admin/base_controller.rb

@@ -12,7 +12,7 @@ module Trackguard
       end
 
       def valid_api_token?
-        expected = Trackguard.api_token
+        expected = Trackguard.local_api_token
         return false unless expected.present?
 
         token = request.headers["Authorization"]&.then { |h| h[/\ABearer (.+)\z/, 1] }

data/app/controllers/trackguard/admin/visitors_controller.rb

@@ -16,9 +16,11 @@ module Trackguard
       # rubocop:disable Metrics/AbcSize
       def flag
         if @visitor.update(
+          suspicious_state: "blocked",
           flagged_at: Time.current,
           flag_reason: params[:flag_reason].presence,
           flagged_by: params[:flagged_by].presence || Visitor::FLAGGED_BY.first,
+          suspicious_since_at: nil,
           name: params[:name].presence || BlockedUserAgent.matching_pattern(@visitor.user_agent)
         )
           respond_to do |format|
@@ -35,7 +37,8 @@ module Trackguard
       # rubocop:enable Metrics/AbcSize
 
       def unflag
-        @visitor.update!(flagged_at: nil, flag_reason: nil, flagged_by: nil)
+        @visitor.update!(suspicious_state: "normal", suspicious_since_at: nil,
+                         flagged_at: nil, flag_reason: nil, flagged_by: nil)
         respond_to do |format|
           format.html { redirect_back_or_to after_action_path }
           format.json { render json: { status: "ok", ip: @visitor.ip } }

data/app/controllers/trackguard/page_views_controller.rb

@@ -9,7 +9,7 @@ module Trackguard
         session_id: session.id.to_s,
         trace_id: params[:trace_id].to_s.presence,
         source: params[:ref].to_s.strip.downcase.first(64).presence,
-        initial: params[:initial] == true,
+        tracking_layer: "js",
         http_method: "GET"
       )
 

data/app/helpers/trackguard/hub_helper.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Trackguard
+  module HubHelper
+    def trackguard_hub_js_tag
+      return unless Trackguard.adapter.is_a?(Trackguard::Adapters::Hub)
+
+      tag.script(src: "https://app.trackguard.dev/track.js", data: { api_key: Trackguard.hub_api_key })
+    end
+  end
+end

data/app/jobs/trackguard/detect_suspicious_visitors_job.rb

@@ -24,7 +24,7 @@ module Trackguard
                          .joins(:visitor)
                          .merge(Visitor.unflagged)
                          .preload(visitor: :whitelisted_ip)
-                         .select(:visitor_id, :session_id, :referer, :path, :trace_id)
+                         .select(:visitor_id, :session_id, :referer, :path, :trace_id, :tracking_layer)
                          .group_by(&:visitor)
 
       return if views_by_visitor.empty?
@@ -44,18 +44,29 @@ module Trackguard
 
       name = name_from_ua(visitor.user_agent)
 
+      if visitor.suspicious?
+        new_views = PageView
+                    .where(visitor: visitor)
+                    .where("created_at > ?", visitor.suspicious_since_at)
+                    .select(:tracking_layer, :trace_id)
+        result = evaluate_suspicious_escalation(visitor, new_views)
+        return if %i[blocked recovered].include?(result)
+      elsif views.any?(&:backend_layer?) && views.none?(&:js_layer?)
+        mark_suspicious!(visitor, name)
+      end
+
       if count >= HARD_FLAG_THRESHOLD
-        flag!(visitor, "#{count} page views in 24h (hard flag threshold)", name: name)
+        mark_blocked!(visitor, "#{count} page views in 24h (hard flag threshold)", name: name)
         return
       end
 
       if (reason = ua_flag_reason(visitor.user_agent))
-        flag!(visitor, reason, name: name)
+        mark_blocked!(visitor, reason, name: name)
         return
       end
 
       if (path = probe_path_hit(views))
-        flag!(visitor, "probe path hit: #{path}", name: name)
+        mark_blocked!(visitor, "probe path hit: #{path}", name: name)
         return
       end
 
@@ -64,7 +75,7 @@ module Trackguard
       return if count < MIN_VIEWS
 
       if views.all? { |pv| pv.session_id.nil? && pv.referer.nil? } && views.map(&:path).uniq.size == 1
-        flag!(visitor, "no session, no referrer, single path hit", name: name)
+        mark_blocked!(visitor, "no session, no referrer, single path hit", name: name)
         return
       end
 
@@ -86,10 +97,34 @@ module Trackguard
 
       return if score < FLAG_SCORE_THRESHOLD
 
-      flag!(visitor, reasons.join("; "), name: name)
+      mark_blocked!(visitor, reasons.join("; "), name: name)
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
+    def evaluate_suspicious_escalation(visitor, new_views)
+      return :unchanged if new_views.empty?
+
+      js_ids = new_views.select { |pv| pv.tracking_layer == "js" }.map(&:trace_id).compact
+
+      if any_unpaired_backend?(new_views, js_ids)
+        mark_blocked!(visitor, "continued backend-only visits since suspicious flag")
+        :blocked
+      elsif paired_backend_trace_ids(new_views, js_ids).any?
+        mark_normal!(visitor)
+        :recovered
+      else
+        :unchanged
+      end
+    end
+
+    def any_unpaired_backend?(views, js_trace_ids)
+      views.any? { |pv| pv.backend_layer? && !js_trace_ids.include?(pv.trace_id) }
+    end
+
+    def paired_backend_trace_ids(views, js_trace_ids)
+      views.select(&:backend_layer?).map(&:trace_id).compact & js_trace_ids
+    end
+
     def flag_shared_trace_id_visitors(cutoff)
       shared = PageView
                .where(created_at: cutoff..)
@@ -108,8 +143,8 @@ module Trackguard
         .where("wi.id IS NULL OR wi.expires_at <= ?", Time.current)
         .distinct
         .each do |visitor|
-          flag!(visitor, "trace_id shared across multiple visitors (cross-visitor bot detected)",
-                name: name_from_ua(visitor.user_agent))
+          mark_blocked!(visitor, "trace_id shared across multiple visitors (cross-visitor bot detected)",
+                        name: name_from_ua(visitor.user_agent))
         end
     end
 
@@ -125,8 +160,27 @@ module Trackguard
       "malformed user-agent (duplicate)" if user_agent.scan("Mozilla/5.0").size > 1
     end
 
-    def flag!(visitor, reason, name: nil)
-      visitor.update!(flagged_at: Time.current, flag_reason: reason, flagged_by: "claw:auto", name: name)
+    def mark_suspicious!(visitor, name)
+      return if visitor.suspicious? || visitor.blocked?
+
+      visitor.update!(suspicious_state: "suspicious", suspicious_since_at: Time.current, name: name)
+    end
+
+    def mark_normal!(visitor)
+      return if visitor.normal? || visitor.blocked?
+
+      visitor.update!(suspicious_state: "normal", suspicious_since_at: nil)
+    end
+
+    def mark_blocked!(visitor, reason, name: nil)
+      visitor.update!(
+        suspicious_state: "blocked",
+        flagged_at: Time.current,
+        flag_reason: reason,
+        flagged_by: "Recurring Job",
+        suspicious_since_at: nil,
+        name: name
+      )
     end
 
     def name_from_ua(user_agent)

data/app/jobs/trackguard/track_page_view_job.rb

@@ -2,29 +2,10 @@ module Trackguard
   class TrackPageViewJob < ApplicationJob
     queue_as :default
 
-    def perform(path:, ip:, user_agent:, referer:, session_id: nil, trace_id: nil, source: nil, initial: false,
-                http_method: nil)
-      hashed_session_id = Digest::SHA256.hexdigest(session_id) if session_id.present?
-
-      visitor = Visitor.find_or_create_by!(ip: ip) do |v|
-        v.user_agent    = user_agent
-        v.first_seen_at = Time.current
-        v.last_seen_at  = Time.current
-      end
-      visitor.update!(last_seen_at: Time.current, user_agent: user_agent)
-
-      if initial && trace_id.present?
-        existing = PageView.find_by(trace_id: trace_id, visitor: visitor)
-        if existing
-          if path.include?("#") && !existing.path.include?("#") && path.start_with?("#{existing.path}#")
-            existing.update!(path: path)
-          end
-          return
-        end
-      end
-
-      PageView.create_with(source:, referer:, http_method:)
-              .find_or_create_by!(path:, user_agent:, session_id: hashed_session_id, trace_id:, visitor:)
+    def perform(path:, ip:, user_agent:, referer:, session_id: nil, trace_id: nil, source: nil,
+                tracking_layer: nil, http_method: nil)
+      TrackPageView.call(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, tracking_layer:,
+                         http_method:)
     end
   end
 end

data/app/models/trackguard/page_view.rb

@@ -6,5 +6,8 @@ module Trackguard
     scope :this_month,    -> { where(created_at: 1.month.ago..) }
     scope :with_referrer, -> { where.not(referer: [ nil, "" ]) }
     scope :with_source,   -> { where.not(source: [ nil, "" ]) }
+
+    def js_layer?      = tracking_layer == "js"
+    def backend_layer? = tracking_layer == "backend"
   end
 end

data/app/models/trackguard/visitor.rb

@@ -2,17 +2,25 @@ module Trackguard
   class Visitor < ApplicationRecord
     self.table_name = "trackguard_visitors"
 
-    FLAGGED_BY = [ "User", "claw:auto" ].freeze
-    CACHE_KEY = "trackguard/flagged_ips".freeze
+    FLAGGED_BY        = [ "User", "claw:auto", "Recurring Job", "Internal Automation", "External Automation" ].freeze
+    SUSPICIOUS_STATES = %w[normal suspicious blocked].freeze
+    CACHE_KEY         = "trackguard/flagged_ips".freeze
 
     validates :flagged_by, inclusion: { in: FLAGGED_BY }, allow_blank: true
+    validates :suspicious_state, inclusion: { in: SUSPICIOUS_STATES }
 
     has_many :page_views,       class_name: "Trackguard::PageView", foreign_key: "visitor_id"
     has_many :blocked_requests, class_name: "Trackguard::BlockedRequest",  foreign_key: "visitor_id"
     has_one  :whitelisted_ip,   class_name: "Trackguard::WhitelistedIp",   foreign_key: "visitor_id"
 
-    scope :unflagged, -> { where(flagged_at: nil) }
-    scope :flagged,   -> { where.not(flagged_at: nil) }
+    scope :unflagged,           -> { where(flagged_at: nil) }
+    scope :flagged,             -> { where.not(flagged_at: nil) }
+    scope :suspicious_visitors, -> { where(suspicious_state: "suspicious") }
+    scope :blocked,             -> { where(suspicious_state: "blocked") }
+
+    def normal?     = suspicious_state == "normal"
+    def suspicious? = suspicious_state == "suspicious"
+    def blocked?    = suspicious_state == "blocked"
 
     def self.flagged?(ip)
       flagged_ips = Rails.cache.fetch(CACHE_KEY, expires_in: 5.minutes) do

data/app/services/trackguard/track_page_view.rb

@@ -0,0 +1,35 @@
+module Trackguard
+  class TrackPageView < ApplicationService
+    def initialize(path:, ip:, user_agent:, referer:, session_id: nil, trace_id: nil,
+                   source: nil, tracking_layer: nil, http_method: nil, visitor_scope: {})
+      @path           = path
+      @ip             = ip
+      @user_agent     = user_agent
+      @referer        = referer
+      @session_id     = session_id
+      @trace_id       = trace_id
+      @source         = source
+      @tracking_layer = tracking_layer
+      @http_method    = http_method
+      @visitor_scope  = visitor_scope
+    end
+
+    def call
+      hashed_session_id = Digest::SHA256.hexdigest(@session_id) if @session_id.present?
+
+      visitor = Visitor.find_or_create_by!(ip: @ip, **@visitor_scope) do |v|
+        v.user_agent    = @user_agent
+        v.first_seen_at = Time.current
+        v.last_seen_at  = Time.current
+      end
+      visitor.update!(last_seen_at: Time.current, user_agent: @user_agent)
+
+      PageView.create!(
+        path: @path, user_agent: @user_agent, session_id: hashed_session_id,
+        trace_id: @trace_id, source: @source, referer: @referer,
+        http_method: @http_method, tracking_layer: @tracking_layer,
+        visitor: visitor, **@visitor_scope
+      )
+    end
+  end
+end

data/app/views/trackguard/admin/_visit_row.html.erb

@@ -1,7 +1,8 @@
 <% visitor     = pv.visitor %>
-<% flagged     = visitor&.flagged_at.present? %>
+<% flagged     = visitor&.blocked? %>
+<% suspicious  = visitor&.suspicious? %>
 <% whitelisted = visitor&.whitelisted_ip&.active? %>
-<% row_classes = [ ("tg-row--flagged" if flagged), ("tg-row--whitelisted" if whitelisted) ].compact.join(" ") %>
+<% row_classes = [ ("tg-row--flagged" if flagged), ("tg-row--suspicious" if suspicious), ("tg-row--whitelisted" if whitelisted) ].compact.join(" ") %>
 <tr class="<%= row_classes %>">
   <td class="tg-td--bare">
     <details>
@@ -11,9 +12,13 @@
         <span class="tg-summary__path"><%= pv.path %></span>
         <span class="tg-summary__flag">
           <% if flagged %>
-            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="tg-flag-icon" title="Flagged">
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="tg-flag-icon" title="Blocked">
               <path fill-rule="evenodd" d="M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z" clip-rule="evenodd" />
             </svg>
+          <% elsif suspicious %>
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="tg-suspicious-icon" title="Suspicious">
+              <path fill-rule="evenodd" d="M18 10a8 8 0 1 1-16 0 8 8 0 0 1 16 0Zm-8-5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0v-4.5A.75.75 0 0 1 10 5Zm0 10a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z" clip-rule="evenodd" />
+            </svg>
           <% else %>
             —
           <% end %>
@@ -27,6 +32,15 @@
             —
           <% end %>
         </span>
+        <span class="tg-summary__layer">
+          <% if pv.tracking_layer == "js" %>
+            <span class="tg-layer-badge tg-layer-badge--js">js</span>
+          <% elsif pv.tracking_layer == "backend" %>
+            <span class="tg-layer-badge tg-layer-badge--backend">srv</span>
+          <% else %>
+            —
+          <% end %>
+        </span>
         <span class="tg-summary__time"><%= pv.created_at.strftime("%b %-d, %H:%M") %></span>
       </summary>
       <div class="tg-detail">
@@ -46,7 +60,7 @@
                     class: "tg-btn tg-btn--whitelist",
                     data: { confirm: "Whitelist #{visitor.ip} for 7 days?" } %>
             <% end %>
-            <% if flagged %>
+            <% if flagged || suspicious %>
               <%= button_to "Unflag", _actions[:unflag][:url],
                     method: _actions[:unflag][:method],
                     params: _actions[:unflag][:params],
@@ -88,15 +102,19 @@
                 <span class="tg-dl__def"><%= visitor&.name.presence || "—" %></span>
               </div>
               <div class="tg-dl__row">
-                <span class="tg-dl__term">Flag status</span>
+                <span class="tg-dl__term">Status</span>
                 <% if flagged %>
                   <span class="tg-dl__def tg-dl__def--flagged">
-                    Flagged <%= visitor.flagged_at.strftime("%b %-d %Y, %H:%M") %>
+                    Blocked <%= visitor.flagged_at.strftime("%b %-d %Y, %H:%M") %>
                     <% if visitor.flagged_by.present? %> by <strong><%= visitor.flagged_by %></strong><% end %>
                     <% if visitor.flag_reason.present? %> — <%= visitor.flag_reason %><% end %>
                   </span>
+                <% elsif suspicious %>
+                  <span class="tg-dl__def tg-dl__def--suspicious">
+                    Suspicious since <%= visitor.suspicious_since_at.strftime("%b %-d %Y, %H:%M") %>
+                  </span>
                 <% else %>
-                  <span class="tg-dl__def tg-dl__def--muted">Not flagged</span>
+                  <span class="tg-dl__def tg-dl__def--muted">Normal</span>
                 <% end %>
               </div>
               <div class="tg-dl__row">
@@ -130,6 +148,15 @@
                 <span class="tg-dl__term">Source</span>
                 <span class="tg-dl__def"><%= pv.source.presence || "—" %></span>
               </div>
+              <div class="tg-dl__row">
+                <span class="tg-dl__term">Layer</span>
+                <span class="tg-dl__def">
+                  <% if pv.tracking_layer == "js" %>JS (client)
+                  <% elsif pv.tracking_layer == "backend" %>Backend (server)
+                  <% else %><span class="tg-dl__def--muted">—</span>
+                  <% end %>
+                </span>
+              </div>
             </div>
           </div>
         </div>

data/lib/generators/trackguard/install_generator.rb

@@ -18,6 +18,10 @@ module Trackguard
       migration_template "create_trackguard_blocked_user_agents.rb",
                          "db/migrate/create_trackguard_blocked_user_agents.rb"
       migration_template "create_trackguard_blocked_paths.rb", "db/migrate/create_trackguard_blocked_paths.rb"
+      migration_template "add_tracking_layer_to_trackguard_visits.rb",
+                         "db/migrate/add_tracking_layer_to_trackguard_visits.rb"
+      migration_template "add_suspicious_state_to_trackguard_visitors.rb",
+                         "db/migrate/add_suspicious_state_to_trackguard_visitors.rb"
     end
 
     def print_next_steps

data/lib/generators/trackguard/templates/add_suspicious_state_to_trackguard_visitors.rb

@@ -0,0 +1,12 @@
+class AddSuspiciousStateToTrackguardVisitors < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :trackguard_visitors, :suspicious_state, :string, null: false, default: "normal"
+    add_column :trackguard_visitors, :suspicious_since_at, :datetime
+
+    reversible do |dir|
+      dir.up do
+        execute "UPDATE trackguard_visitors SET suspicious_state = 'blocked' WHERE flagged_at IS NOT NULL"
+      end
+    end
+  end
+end

data/lib/generators/trackguard/templates/add_tracking_layer_to_trackguard_visits.rb

@@ -0,0 +1,5 @@
+class AddTrackingLayerToTrackguardVisits < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :trackguard_visits, :tracking_layer, :string
+  end
+end

data/lib/generators/trackguard/templates/create_trackguard_visits.rb

@@ -10,6 +10,7 @@ class CreateTrackguardVisits < ActiveRecord::Migration[<%= ActiveRecord::Migrati
       t.string    :source
       t.string    :block_reason
       t.string    :http_method
+      t.string    :tracking_layer
       t.references :visitor,     null: false, foreign_key: { to_table: :trackguard_visitors }
       t.datetime  :created_at,   null: false
     end

data/lib/tasks/trackguard.rake

@@ -72,41 +72,26 @@ namespace :trackguard do
       next
     end
 
-    base_version       = File.basename(monolithic).match(/\A(\d{14})/)[1].to_i
-    monolithic_content = File.read(monolithic)
-    template_dir       = Trackguard::Engine.root.join("lib", "generators", "trackguard", "templates")
-    conn               = ActiveRecord::Base.connection
+    base_version = File.basename(monolithic).match(/\A(\d{14})/)[1].to_i
+    template_dir = Trackguard::Engine.root.join("lib", "generators", "trackguard", "templates")
 
     splits = [
-      [ base_version,     "create_trackguard_visitors",            "trackguard_visitors" ],
-      [ base_version + 1, "create_trackguard_visits",              "trackguard_visits" ],
-      [ base_version + 2, "create_trackguard_whitelisted_ips",     "trackguard_whitelisted_ips" ],
-      [ base_version + 3, "create_trackguard_blocked_user_agents", "trackguard_blocked_user_agents" ],
-      [ base_version + 4, "create_trackguard_blocked_paths",       "trackguard_blocked_paths" ]
+      [ base_version,     "create_trackguard_visitors" ],
+      [ base_version + 1, "create_trackguard_visits" ],
+      [ base_version + 2, "create_trackguard_whitelisted_ips" ],
+      [ base_version + 3, "create_trackguard_blocked_user_agents" ],
+      [ base_version + 4, "create_trackguard_blocked_paths" ]
     ]
 
-    # Only inject entries for tables the monolithic actually created.
-    # Tables absent from it are left for `rails generate trackguard:install` + `db:migrate`.
-    to_inject, to_defer = splits.partition { |_, _, table| monolithic_content.include?("create_table :#{table}") }
-
-    new_versions = to_inject.map { |ts, _, _| ts }.reject { |ts| ts == base_version }
-    create_list  = to_inject.map { |ts, name, _| "  db/migrate/#{ts}_#{name}.rb" }.join("\n")
+    create_list = splits.map { |ts, name| "  db/migrate/#{ts}_#{name}.rb" }.join("\n")
 
     puts "This will make the following changes to your application:"
     puts ""
     puts "  Remove:  db/migrate/#{File.basename(monolithic)}"
-    puts "  Create:"
+    puts "  Create (table/index creation guarded with if_not_exists):"
     puts create_list
     puts ""
-    puts "  Update schema_migrations: add versions #{new_versions.join(', ')}" if new_versions.any?
-    puts "  Update db/schema.rb if its version points at #{base_version}"
-    if to_defer.any?
-      puts ""
-      puts "  Not in monolithic — deferred to install generator + db:migrate:"
-      to_defer.each { |_, name, _| puts "    #{name}" }
-    end
-    puts ""
-    puts "  Tables themselves are NOT touched. Bookkeeping only."
+    puts "  Run `rails db:migrate` afterwards — existing tables and indexes are skipped safely."
     puts ""
 
     $stdout.print "Proceed? [y/N] "
@@ -118,44 +103,23 @@ namespace :trackguard do
 
     puts ""
 
-    sm_insert = lambda do |v|
-      quoted = conn.quote(v.to_s)
-      unless conn.select_value("SELECT 1 FROM schema_migrations WHERE version = #{quoted}")
-        conn.execute("INSERT INTO schema_migrations (version) VALUES (#{quoted})")
-      end
-    end
-
-    last_injected = base_version
-
-    to_inject.each do |ts, name, _|
+    splits.each do |ts, name|
       path = migrate_dir.join("#{ts}_#{name}.rb")
       if path.exist?
         puts "  skip   #{path.basename}"
       else
-        content = ERB.new(File.read(template_dir.join("#{name}.rb"))).result(binding)
-        path.write(content)
+        raw = ERB.new(File.read(template_dir.join("#{name}.rb"))).result(binding)
+        guarded = raw
+                  .gsub(/create_table (\S+) do/, 'create_table \1, if_not_exists: true do')
+                  .gsub(/^(\s+add_index .+)$/, '\1, if_not_exists: true')
+        path.write(guarded)
         puts "  create #{path.basename}"
       end
-      sm_insert.call(ts)
-      last_injected = ts
     end
 
     FileUtils.rm(monolithic)
     puts "  remove #{File.basename(monolithic)}"
-    # base_version stays in schema_migrations — it now belongs to create_trackguard_visitors
-
-    schema_path = Rails.root.join("db", "schema.rb")
-    if schema_path.exist? && last_injected != base_version
-      schema_content = schema_path.read
-      if schema_content.include?("version: #{base_version}")
-        schema_path.write(schema_content.sub("version: #{base_version}", "version: #{last_injected}"))
-        puts "  update db/schema.rb: version #{base_version} → #{last_injected}"
-      end
-    end
 
-    if to_defer.any?
-      puts "\nRun `rails generate trackguard:install && rails db:migrate` to create the remaining tables."
-    end
-    puts "\nDone. Run `rails db:migrate:status` to verify."
+    puts "\nDone. Run `rails db:migrate` to apply any missing migrations."
   end
 end

data/lib/trackguard/adapters/base.rb

@@ -8,7 +8,8 @@ module Trackguard
       def whitelisted_ip?(ip)             = raise NotImplementedError, "#{self.class}#whitelisted_ip?"
       def flagged_visitor?(ip)            = raise NotImplementedError, "#{self.class}#flagged_visitor?"
 
-      def track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, initial:, http_method:)
+      def track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, tracking_layer:,
+                          http_method:)
         return if blocked_user_agent?(user_agent)
         return if blocked_path?(path)
         return if path.blank? || path.start_with?(Trackguard.admin_path)
@@ -16,7 +17,7 @@ module Trackguard
         perform_track_page_view(
           path: path, ip: ip, user_agent: user_agent, referer: referer,
           session_id: session_id, trace_id: trace_id, source: source,
-          initial: initial, http_method: http_method
+          tracking_layer: tracking_layer, http_method: http_method
         )
       end
 
@@ -26,8 +27,8 @@ module Trackguard
 
       protected
 
-      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, initial:,
-                                  http_method:)
+      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:,
+                                  tracking_layer:, http_method:)
         raise NotImplementedError, "#{self.class}#perform_track_page_view"
       end
     end

data/lib/trackguard/adapters/hub.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Trackguard
+  module Adapters
+    class Hub < Base
+      CACHE_KEY = "trackguard/hub_rules"
+      STALE_KEY = "trackguard/hub_rules/stale"
+      ETAG_KEY  = "trackguard/hub_rules/etag"
+
+      def blocked_user_agent?(user_agent)
+        rules.fetch(:blocked_user_agents, []).any? do |p|
+          user_agent.to_s.downcase.include?(p.downcase)
+        end
+      end
+
+      def blocked_path?(path)
+        rules.fetch(:blocked_paths, []).any? do |p|
+          path.to_s.downcase.include?(p.downcase)
+        end
+      end
+
+      def whitelisted_ip?(ip)
+        rules.fetch(:whitelisted_ips, []).include?(ip)
+      end
+
+      def flagged_visitor?(ip)
+        rules.fetch(:flagged_ips, []).include?(ip)
+      end
+
+      def track_blocked_request(ip:, user_agent:, path:, http_method:, block_reason:)
+        # placeholder: hub adapter does not persist blocked requests locally
+      end
+
+      protected
+
+      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:,
+                                  tracking_layer:, http_method:)
+        # placeholder: hub tracking not yet implemented
+      end
+
+      private
+
+      def rules
+        Rails.cache.fetch(CACHE_KEY, expires_in: Trackguard.hub_rules_ttl, race_condition_ttl: 10) do
+          fresh = fetch_rules_from_hub
+          Rails.cache.write(STALE_KEY, fresh, expires_in: 24.hours)
+          fresh
+        end
+      rescue StandardError => e
+        Rails.logger.warn("[Trackguard::Adapters::Hub] Failed to fetch rules: #{e.message}")
+        Rails.cache.read(STALE_KEY) || {}
+      end
+
+      def fetch_rules_from_hub
+        uri = URI("#{Trackguard.hub_url}/api/rules")
+        request = Net::HTTP::Get.new(uri)
+        request["Authorization"] = "Bearer #{Trackguard.hub_secret_key}"
+        request["Accept"] = "application/json"
+
+        etag = Rails.cache.read(ETAG_KEY)
+        request["If-None-Match"] = etag if etag
+
+        response = Net::HTTP.start(
+          uri.hostname, uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: 3,
+          read_timeout: 5
+        ) do |http|
+          http.request(request)
+        end
+
+        return Rails.cache.read(STALE_KEY) || {} if response.is_a?(Net::HTTPNotModified)
+
+        raise "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        fresh = JSON.parse(response.body, symbolize_names: true)
+        Rails.cache.write(ETAG_KEY, response["ETag"], expires_in: 24.hours) if response["ETag"]
+        fresh
+      end
+    end
+  end
+end

data/lib/trackguard/adapters/local.rb

@@ -31,8 +31,8 @@ module Trackguard
 
       protected
 
-      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:, initial:,
-                                  http_method:)
+      def perform_track_page_view(path:, ip:, user_agent:, referer:, session_id:, trace_id:, source:,
+                                  tracking_layer:, http_method:)
         TrackPageViewJob.perform_later(
           path: path,
           ip: ip,
@@ -41,7 +41,7 @@ module Trackguard
           session_id: session_id,
           trace_id: trace_id,
           source: source,
-          initial: initial,
+          tracking_layer: tracking_layer,
           http_method: http_method
         )
       end

data/lib/trackguard/engine.rb

@@ -4,10 +4,9 @@ module Trackguard
   class Engine < ::Rails::Engine
     isolate_namespace Trackguard
 
-    initializer "trackguard.helpers" do
-      ActiveSupport.on_load(:action_controller) do
-        helper Trackguard::ApplicationHelper
-      end
+    config.to_prepare do
+      ActionController::Base.helper Trackguard::ApplicationHelper
+      ActionController::Base.helper Trackguard::HubHelper
     end
 
     initializer "trackguard.assets" do |app|

data/lib/trackguard/version.rb

@@ -1,3 +1,3 @@
 module Trackguard
-  VERSION = "0.27.0".freeze
+  VERSION = "0.28.0".freeze
 end

data/lib/trackguard.rb

@@ -5,11 +5,13 @@ require "trackguard/engine"
 require "trackguard/rack_attack"
 require "trackguard/adapters/base"
 require "trackguard/adapters/local"
+require "trackguard/adapters/hub"
 
 module Trackguard
   class << self
-    attr_writer :authenticate_admin_with, :admin_layout, :admin_path, :back_label, :api_token, :throttle_limit,
-                :throttle_period
+    attr_writer :authenticate_admin_with, :admin_layout, :admin_path, :back_label, :local_api_token, :throttle_limit,
+                :throttle_period, :hub_secret_key, :hub_api_key, :hub_rules_ttl
+    attr_accessor :hub_url
 
     def authenticate_admin_with
       @authenticate_admin_with ||= proc {}
@@ -27,8 +29,8 @@ module Trackguard
       @back_label ||= "Back to app"
     end
 
-    def api_token
-      @api_token.to_s
+    def local_api_token
+      @local_api_token.to_s
     end
 
     def throttle_limit
@@ -39,6 +41,10 @@ module Trackguard
       @throttle_period ||= 60
     end
 
+    def hub_secret_key = @hub_secret_key.to_s
+    def hub_api_key    = @hub_api_key.to_s
+    def hub_rules_ttl = @hub_rules_ttl ||= 5.minutes
+
     def adapter
       @adapter ||= Trackguard::Adapters::Local.new
     end

data/trackguard.gemspec

@@ -15,4 +15,5 @@ Gem::Specification.new do |s|
   s.add_dependency "rack-attack"
   s.add_dependency "rails", ">= 8.1"
   s.metadata["rubygems_mfa_required"] = "true"
+  s.metadata["changelog_uri"]         = "https://github.com/riggy/trackguard/blob/main/CHANGELOG.md"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trackguard
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Krzysztof Rygielski
@@ -58,6 +58,7 @@ files:
 - app/controllers/trackguard/admin/whitelisted_ips_controller.rb
 - app/controllers/trackguard/page_views_controller.rb
 - app/helpers/trackguard/application_helper.rb
+- app/helpers/trackguard/hub_helper.rb
 - app/jobs/trackguard/detect_suspicious_visitors_job.rb
 - app/jobs/trackguard/track_blocked_request_job.rb
 - app/jobs/trackguard/track_page_view_job.rb
@@ -70,6 +71,7 @@ files:
 - app/models/trackguard/whitelisted_ip.rb
 - app/services/trackguard/analytics_query.rb
 - app/services/trackguard/application_service.rb
+- app/services/trackguard/track_page_view.rb
 - app/views/layouts/trackguard/admin.html.erb
 - app/views/trackguard/admin/_nav.html.erb
 - app/views/trackguard/admin/_stats_panel.html.erb
@@ -82,6 +84,8 @@ files:
 - config/importmap.rb
 - config/routes.rb
 - lib/generators/trackguard/install_generator.rb
+- lib/generators/trackguard/templates/add_suspicious_state_to_trackguard_visitors.rb
+- lib/generators/trackguard/templates/add_tracking_layer_to_trackguard_visits.rb
 - lib/generators/trackguard/templates/create_trackguard_blocked_paths.rb
 - lib/generators/trackguard/templates/create_trackguard_blocked_user_agents.rb
 - lib/generators/trackguard/templates/create_trackguard_visitors.rb
@@ -90,6 +94,7 @@ files:
 - lib/tasks/trackguard.rake
 - lib/trackguard.rb
 - lib/trackguard/adapters/base.rb
+- lib/trackguard/adapters/hub.rb
 - lib/trackguard/adapters/local.rb
 - lib/trackguard/engine.rb
 - lib/trackguard/rack_attack.rb
@@ -100,6 +105,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  changelog_uri: https://github.com/riggy/trackguard/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib