@tokenoftrust/storefront-runner 2.2.76 → 2.2.77

package/apps/storefront/src/lib/cspStaticHashes.ts

@@ -19,7 +19,7 @@ export const STATIC_SCRIPT_HASHES: readonly string[] = [
   "'sha256-YicfxUFBkKrQapZ/tzZKlaKTdNHgwVfv7y2Wa0NC6/k='",
   "'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc='",
   "'sha256-elMLh/6Oubj8u9FRLwZLyRa6TqKikGs75mf0jfWcoxI='",
-  "'sha256-n9b6Y8jO/N+uwfItpBlKcnLoRaKnidYcvDkuixl+DwY='",
+  "'sha256-ZxqYN/PbpT0W68E87+IwdGfcYJuAVXNPNVxVb3VX0hw='",
 ];
 
 export const STATIC_STYLE_HASHES: readonly string[] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.76",
+  "version": "2.2.77",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/integration/native-amplitude.ts

@@ -74,6 +74,8 @@ export const NO_SESSION_ID = -1 as const;
 export const VISITOR_CONTINUITY_STORAGE_KEY = "tot.analytics-continuity.v1" as const;
 export const VISITOR_ID_LIFETIME_MS = 90 * 24 * 60 * 60 * 1000;
 export const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
+/** Ceiling on the per-visitor session count; a 90-day id cannot plausibly reach it. */
+export const MAX_VISITOR_SESSION_COUNT = 100_000;
 export const AMPLITUDE_HTTP_EVENT_TYPES = Object.freeze([
   "storefront.page.viewed.v1",
   "storefront.page.viewed.v2",
@@ -184,6 +186,8 @@ export interface VisitorContinuityIds {
   deviceId: string;
   sessionId: number;
   sessionState: VisitorSessionState;
+  /** 1-based count of this visitor's sessions, current one included (GA4's session number). */
+  sessionCount: number;
 }
 
 export interface VisitorContinuity {
@@ -200,14 +204,17 @@ export interface CreateVisitorContinuityOptions {
 }
 
 interface VisitorRecord {
-  schemaVersion: 1;
+  schemaVersion: 2;
   deviceId: string;
   createdAt: number;
   sessionStartedAt: number;
   lastActivityAt: number;
+  sessionCount: number;
 }
 
-const VISITOR_RECORD_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionStartedAt";
+const VISITOR_RECORD_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionCount,sessionStartedAt";
+/** The exact schemaVersion-1 shape, written before the session number existed; upgraded in place. */
+const VISITOR_RECORD_V1_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionStartedAt";
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 export function visitorContinuityStorageKey(scope: VisitorContinuityScope): string {
@@ -215,22 +222,33 @@ export function visitorContinuityStorageKey(scope: VisitorContinuityScope): stri
   return `${VISITOR_CONTINUITY_STORAGE_KEY}:${encodeURIComponent(contextKey)}`;
 }
 
-/** A stored record that is malformed, from the future, or past its fixed lifetime is not a visitor. */
+/**
+ * A stored record that is malformed, from the future, or past its fixed lifetime is not a
+ * visitor. A valid record in the exact schemaVersion-1 shape keeps its id and session and
+ * becomes schemaVersion 2 at session number 1 (the caller writes it back); every other
+ * shape is still refused, so an upgraded visitor is not counted twice.
+ */
 function liveVisitorRecord(raw: string | null, now: number): VisitorRecord | null {
   if (!raw) return null;
   let parsed: unknown;
   try { parsed = JSON.parse(raw); } catch { return null; }
-  if (!isPlainObject(parsed) || Object.keys(parsed).sort().join(",") !== VISITOR_RECORD_KEYS) return null;
+  if (!isPlainObject(parsed)) return null;
+  const keys = Object.keys(parsed).sort().join(",");
   const { schemaVersion, deviceId, createdAt, sessionStartedAt, lastActivityAt } = parsed;
+  let sessionCount = parsed["sessionCount"];
+  if (keys === VISITOR_RECORD_V1_KEYS && schemaVersion === 1) sessionCount = 1;
+  else if (keys !== VISITOR_RECORD_KEYS || schemaVersion !== 2) return null;
   if (
-    schemaVersion !== 1 || typeof deviceId !== "string" || !UUID_PATTERN.test(deviceId) ||
+    typeof deviceId !== "string" || !UUID_PATTERN.test(deviceId) ||
+    typeof sessionCount !== "number" || !Number.isSafeInteger(sessionCount) ||
+    sessionCount < 1 || sessionCount > MAX_VISITOR_SESSION_COUNT ||
     typeof createdAt !== "number" || typeof sessionStartedAt !== "number" ||
     typeof lastActivityAt !== "number" ||
     !Number.isFinite(createdAt) || !Number.isFinite(sessionStartedAt) || !Number.isFinite(lastActivityAt) ||
     createdAt > now || now - createdAt >= VISITOR_ID_LIFETIME_MS ||
     sessionStartedAt < createdAt || lastActivityAt < sessionStartedAt
   ) return null;
-  return { schemaVersion, deviceId, createdAt, sessionStartedAt, lastActivityAt };
+  return { schemaVersion: 2, deviceId, createdAt, sessionStartedAt, lastActivityAt, sessionCount };
 }
 
 function defaultRandomUUID(): string {
@@ -274,14 +292,15 @@ export function createVisitorContinuity(options: CreateVisitorContinuityOptions
           if (!record) {
             const deviceId = mint();
             if (deviceId) {
-              record = { schemaVersion: 1, deviceId, createdAt: now, sessionStartedAt: now, lastActivityAt: now };
+              record = { schemaVersion: 2, deviceId, createdAt: now, sessionStartedAt: now, lastActivityAt: now, sessionCount: 1 };
               started = "first_visit";
             }
           } else {
             const rolled = now - record.lastActivityAt > SESSION_INACTIVITY_MS;
             const sessionStartedAt = rolled ? now : record.sessionStartedAt;
             if (rolled) started = "new_session";
-            record = { ...record, sessionStartedAt, lastActivityAt: Math.max(now, record.lastActivityAt) };
+            const sessionCount = rolled ? Math.min(record.sessionCount + 1, MAX_VISITOR_SESSION_COUNT) : record.sessionCount;
+            record = { ...record, sessionStartedAt, sessionCount, lastActivityAt: Math.max(now, record.lastActivityAt) };
           }
           if (record) {
             store.setItem(key, JSON.stringify(record));
@@ -291,6 +310,7 @@ export function createVisitorContinuity(options: CreateVisitorContinuityOptions
               deviceId: record.deviceId,
               sessionId: record.sessionStartedAt,
               sessionState: stateOf(key, record.sessionStartedAt),
+              sessionCount: record.sessionCount,
             };
           }
         } catch {
@@ -300,11 +320,11 @@ export function createVisitorContinuity(options: CreateVisitorContinuityOptions
       let deviceId = memory.get(key);
       if (!deviceId) {
         const minted = mint();
-        if (!minted) return { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID, sessionState: "first_visit" };
+        if (!minted) return { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID, sessionState: "first_visit", sessionCount: 1 };
         deviceId = minted;
         memory.set(key, deviceId);
       }
-      return { deviceId, sessionId: NO_SESSION_ID, sessionState: "first_visit" };
+      return { deviceId, sessionId: NO_SESSION_ID, sessionState: "first_visit", sessionCount: 1 };
     },
     clear(scope) {
       const key = visitorContinuityStorageKey(scope);
@@ -479,7 +499,7 @@ function createAmplitudeHandler(input: AmplitudeHandlerInput): (event: CommerceE
     if (!mapped || input.dedupe.seenOrRemember(mapped.insert_id)) return;
     let identity: VisitorContinuityIds;
     try { identity = input.continuity.readOrMint(scope, mapped.time); }
-    catch { identity = { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID, sessionState: "first_visit" }; }
+    catch { identity = { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID, sessionState: "first_visit", sessionCount: 1 }; }
     const body = JSON.stringify({
       api_key: input.destinationId,
       events: [{ ...mapped, device_id: identity.deviceId, session_id: identity.sessionId }],

package/packages/public-runtime/src/integration/native-ga4-sandbox-entry.ts

@@ -12,6 +12,8 @@ const CAMPAIGN_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
 const GOVERNED_VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const CLIENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const SESSION_STATES: ReadonlySet<unknown> = new Set(["first_visit", "new_session", "continuing"]);
+/** Ceiling on the session number the parent may claim (its own record caps at the same value). */
+const MAX_SESSION_COUNT = 100_000;
 /** gtag's own session-inactivity window, in seconds. */
 const GTAG_SESSION_TIMEOUT_S = 30 * 60;
 const APPROVED_ACTIONS: ReadonlySet<string> = new Set(APPROVED_MARKETING_ACTION_NAMES);
@@ -65,27 +67,37 @@ function validGovernedProperties(value: unknown): value is Record<string, string
 
 interface FrameVisitor {
   clientId: string;
-  session?: { idSeconds: number; state: "first_visit" | "new_session" | "continuing" };
+  session?: { idSeconds: number; state: "first_visit" | "new_session" | "continuing"; count: number };
 }
 
 /**
- * The visitor crosses the same hostile boundary: a lowercase UUID and, together or not
- * at all, a positive integer epoch-ms session start plus its closed state. Anything else
- * refuses the whole configure rather than falling back to an id gtag would invent.
+ * The visitor crosses the same hostile boundary: a lowercase UUID and, all together or
+ * not at all, a positive integer epoch-ms session start, its closed state, and a capped
+ * positive session number (1 exactly on a first visit, at least 2 on a new session).
+ * Anything else refuses the whole configure rather than falling back to an id gtag would
+ * invent.
  */
 function parseVisitor(value: unknown): FrameVisitor | null {
   const record = plainRecord(value);
-  if (!record || !exactKeys(record, ["clientId", "sessionId", "sessionState"], ["clientId"])) return null;
-  const { clientId, sessionId, sessionState } = record;
+  if (!record || !exactKeys(record, ["clientId", "sessionId", "sessionState", "sessionCount"], ["clientId"])) return null;
+  const { clientId, sessionId, sessionState, sessionCount } = record;
   if (typeof clientId !== "string" || !CLIENT_ID.test(clientId)) return null;
-  if (sessionId === undefined && sessionState === undefined) return { clientId };
+  if (sessionId === undefined && sessionState === undefined && sessionCount === undefined) return { clientId };
   if (
     typeof sessionId !== "number" || !Number.isSafeInteger(sessionId) || sessionId <= 0 ||
-    !SESSION_STATES.has(sessionState)
+    !SESSION_STATES.has(sessionState) ||
+    typeof sessionCount !== "number" || !Number.isSafeInteger(sessionCount) ||
+    sessionCount < 1 || sessionCount > MAX_SESSION_COUNT ||
+    (sessionState === "first_visit" && sessionCount !== 1) ||
+    (sessionState === "new_session" && sessionCount < 2)
   ) return null;
   return {
     clientId,
-    session: { idSeconds: Math.floor(sessionId / 1000), state: sessionState as "first_visit" | "new_session" | "continuing" },
+    session: {
+      idSeconds: Math.floor(sessionId / 1000),
+      state: sessionState as "first_visit" | "new_session" | "continuing",
+      count: sessionCount,
+    },
   };
 }
 
@@ -122,9 +134,11 @@ function installMemoryCookieJar(doc: Document): Map<string, string> {
 
 /**
  * Seed gtag's session cookie so it reports the parent's session: `continuing` gets a
- * live session (no `session_start`, no `first_visit`); `new_session` gets an expired one,
- * so gtag starts a session for a returning visitor; `first_visit` gets none. The field
- * layout is gtag's own; if gtag stops parsing it, collection still carries the parent's
+ * live session (no `session_start`, no `first_visit`) at session number `count`;
+ * `new_session` gets an expired one at `count - 1`, which gtag increments as it starts
+ * the session for a returning visitor; `first_visit` gets none (gtag reports 1). The
+ * GS2 layout is gtag's own and undocumented (`o` is its session counter, measured
+ * 2026-10-06); if gtag stops parsing it, collection still carries the parent's
  * `client_id` and session id and only the new-session / first-visit flags overcount.
  */
 function seedSessionCookies(jar: Map<string, string>, ids: readonly string[], visitor: FrameVisitor | null): void {
@@ -134,8 +148,9 @@ function seedSessionCookies(jar: Map<string, string>, ids: readonly string[], vi
   const nowSeconds = Math.floor(Date.now() / 1000);
   const lastSeen = session.state === "continuing" ? nowSeconds : session.idSeconds - GTAG_SESSION_TIMEOUT_S - 1;
   const sessionStart = session.state === "continuing" ? session.idSeconds : lastSeen;
+  const sessionNumber = session.state === "continuing" ? session.count : session.count - 1;
   for (const id of ids) {
-    jar.set(`_ga_${id.slice("G-".length)}`, `GS2.1.s${sessionStart}$o1$g0$t${lastSeen}$j0$l0$h0`);
+    jar.set(`_ga_${id.slice("G-".length)}`, `GS2.1.s${sessionStart}$o${sessionNumber}$g0$t${lastSeen}$j0$l0$h0`);
   }
 }
 

package/packages/public-runtime/src/integration/native-ga4-sandbox.ts

@@ -28,9 +28,11 @@ export interface NativeGa4SandboxConfig {
 export interface NativeGa4SandboxVisitor {
   /** Lowercase random UUID, the GA4 `client_id`. */
   clientId: string;
-  /** Session start in epoch ms; absent (with `sessionState`) when origin storage is unavailable. */
+  /** Session start in epoch ms; absent (with the other session fields) when origin storage is unavailable. */
   sessionId?: number;
   sessionState?: "first_visit" | "new_session" | "continuing";
+  /** 1-based session number, GA4's `sct`. */
+  sessionCount?: number;
 }
 
 export interface NativeGa4PageViewCommand {

package/packages/public-runtime/src/integration/native-ga4.ts

@@ -161,7 +161,12 @@ function frameVisitor(continuity: VisitorContinuity, scope: VisitorContinuitySco
   if (ids.sessionId === NO_SESSION_ID || !Number.isSafeInteger(ids.sessionId) || ids.sessionId <= 0) {
     return { clientId: ids.deviceId };
   }
-  return { clientId: ids.deviceId, sessionId: ids.sessionId, sessionState: ids.sessionState };
+  return {
+    clientId: ids.deviceId,
+    sessionId: ids.sessionId,
+    sessionState: ids.sessionState,
+    sessionCount: ids.sessionCount,
+  };
 }
 
 function hasAnalyticsConsent(ctx: IntegrationLifecycleContext): boolean {

package/scripts/dev/ga4-gs2-canary.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// ga4-gs2-canary.mjs — does gtag.js still read the GA4 sandbox's seeded session cookie?
+//
+// The sandbox frame seeds gtag's `_ga_<container>` cookie (Google's undocumented GS2 format)
+// into an in-memory jar so GA4 reports the parent's visitor and session. This loads the BUILT
+// sandbox document and the CURRENT live gtag.js in headless Chromium, drives three page loads
+// (first visit, continuing, new session) through the real bind/configure protocol, and asserts
+// what gtag puts on /g/collect. Every collect request is ABORTED: nothing reaches Google.
+//
+// Needs the network (gtag.js), so it is a canary, not a CI test. Exit 0 = gtag behaves as the
+// seed expects; 1 = drift (the docs say what GA4 then reports); 2 = could not run.
+//
+// Usage: node scripts/dev/ga4-gs2-canary.mjs
+import { createRequire } from "node:module";
+
+const storefrontRequire = createRequire(new URL("../../apps/storefront/package.json", import.meta.url));
+let chromium;
+let buildGoogleMeasurementSandboxHtml;
+try {
+  ({ chromium } = storefrontRequire("@playwright/test"));
+  ({ buildGoogleMeasurementSandboxHtml } = await import("../../apps/storefront/integrations/google-measurement-sandbox-asset.mjs"));
+} catch (error) {
+  console.error(`ga4-gs2-canary: cannot run — ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(2);
+}
+
+const PARENT = "https://shop.canary.test";
+const FRAME = "https://www.shop.canary.test/platform/google-measurement/v2/sandbox.html";
+const MEASUREMENT_ID = "G-CANARY0001";
+const CLIENT_ID = "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
+const FIRST_SESSION_MS = Date.now() - 5 * 60 * 1000;
+const SECOND_SESSION_MS = Date.now();
+const seconds = (ms) => String(Math.floor(ms / 1000));
+
+const LOADS = [
+  {
+    name: "first visit",
+    visitor: { clientId: CLIENT_ID, sessionId: FIRST_SESSION_MS, sessionState: "first_visit", sessionCount: 1 },
+    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: "1", _fv: "1" },
+  },
+  {
+    name: "next page, same session",
+    visitor: { clientId: CLIENT_ID, sessionId: FIRST_SESSION_MS, sessionState: "continuing", sessionCount: 1 },
+    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: null, _fv: null },
+  },
+  {
+    name: "return, new session",
+    visitor: { clientId: CLIENT_ID, sessionId: SECOND_SESSION_MS, sessionState: "new_session", sessionCount: 2 },
+    expect: { cid: CLIENT_ID, sid: seconds(SECOND_SESSION_MS), sct: "2", _ss: "1", _fv: null },
+  },
+];
+
+const parentPage = (visitor) => `<!doctype html><body><script>
+const frame = document.createElement("iframe");
+frame.setAttribute("sandbox", "allow-scripts allow-same-origin");
+frame.src = ${JSON.stringify(FRAME)};
+frame.addEventListener("load", () => {
+  const channel = new MessageChannel();
+  frame.contentWindow.postMessage({ protocol: "tot.ga4-sandbox/1", type: "bind", parentOrigin: location.origin }, new URL(frame.src).origin, [channel.port2]);
+  channel.port1.postMessage({ schemaVersion: 1, type: "configure", destinationIds: [${JSON.stringify(MEASUREMENT_ID)}],
+    canonicalOrigin: location.origin, analyticsConsent: "granted",
+    governedProperties: { tenant: "canary", environment: "live", site_surface: "storefront" },
+    visitor: ${JSON.stringify(visitor)} });
+  channel.port1.postMessage({ schemaVersion: 1, type: "page_view", path: "/canary" });
+});
+document.body.append(frame);
+</script></body>`;
+
+const html = await buildGoogleMeasurementSandboxHtml();
+const browser = await chromium.launch();
+const failures = [];
+let gtagLoaded = false;
+try {
+  const context = await browser.newContext();
+  const pageViews = new Map();
+  let current = 0;
+  await context.route("**/*", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    if (request.url().startsWith(FRAME)) return route.fulfill({ status: 200, contentType: "text/html", body: html });
+    if (url.origin === PARENT) return route.fulfill({ status: 200, contentType: "text/html", body: parentPage(LOADS[current].visitor) });
+    if (url.host === "www.googletagmanager.com" && url.pathname === "/gtag/js") {
+      gtagLoaded = true;
+      return route.continue();
+    }
+    if (url.pathname.endsWith("/g/collect")) {
+      for (const line of [url.search.slice(1), ...(request.postData() ?? "").split("\n")].filter(Boolean)) {
+        const params = new URLSearchParams(url.search);
+        for (const [key, value] of new URLSearchParams(line)) params.set(key, value);
+        if (params.get("en") === "page_view" && !pageViews.has(current)) {
+          pageViews.set(current, Object.fromEntries(["cid", "sid", "sct", "_ss", "_fv"].map((key) => [key, params.get(key)])));
+        }
+      }
+    }
+    return route.abort();
+  });
+  const page = await context.newPage();
+  for (current = 0; current < LOADS.length; current += 1) {
+    await page.goto(`${PARENT}/?load=${current}`);
+    for (let waited = 0; !pageViews.has(current) && waited < 15_000; waited += 250) await page.waitForTimeout(250);
+    await page.goto("about:blank");
+    await page.waitForTimeout(500);
+  }
+  const cookies = await context.cookies([FRAME, PARENT]);
+
+  if (!gtagLoaded) {
+    console.error("ga4-gs2-canary: cannot run — gtag.js never loaded (network?)");
+    process.exitCode = 2;
+  } else {
+    LOADS.forEach((load, index) => {
+      const actual = pageViews.get(index);
+      if (!actual) return failures.push(`${load.name}: no page_view reached /g/collect`);
+      for (const [key, value] of Object.entries(load.expect)) {
+        if (actual[key] !== value) failures.push(`${load.name}: ${key}=${actual[key]} (expected ${value})`);
+      }
+      console.log(`${load.name}: ${JSON.stringify({ ...actual, cid: actual.cid === CLIENT_ID ? "<seeded>" : actual.cid })}`);
+    });
+    if (cookies.length > 0) failures.push(`cookies written on the frame or parent origin: ${cookies.map((c) => c.name).join(", ")}`);
+    if (failures.length > 0) {
+      console.error("ga4-gs2-canary: DRIFT — gtag no longer honours the sandbox seed as expected:");
+      for (const failure of failures) console.error(`  - ${failure}`);
+      console.error("See docs/architecture/analytics-activation.md (GA4) for what GA4 reports in this state.");
+      process.exitCode = 1;
+    } else {
+      console.log("ga4-gs2-canary: OK — gtag reads the GS2 seed; cid, sid, sct, _ss and _fv match, no cookies written.");
+    }
+  }
+} finally {
+  await browser.close();
+}