@tokenoftrust/storefront-runner 2.0.40 → 2.0.42

package/packages/public-runtime/src/integration/consent-broker.ts

@@ -475,10 +475,10 @@ export class ConsentBroker {
 /**
  * Viewer-owned analytics consent for the public storefront document.
  *
- * The tenant configuration says which purposes may exist; it never speaks for the
- * viewer. This controller therefore removes a baked analytics grant until the viewer
- * has made an explicit, unexpired choice. The same synchronous early boot runs in both
- * document mounts before any integration or measurement loader can execute.
+ * The tenant configuration supplies the analytics default and a stored viewer choice
+ * overrides it. Global Privacy Control always denies analytics. The same synchronous
+ * early boot runs in both document mounts before any integration or measurement loader
+ * can execute.
  */
 
 export const VIEWER_ANALYTICS_CONSENT_STORAGE_KEY = "tot.viewer-analytics-consent.v1";
@@ -492,7 +492,7 @@ export type ViewerAnalyticsConsentDecision = "granted" | "denied";
 export interface ViewerAnalyticsConsentState {
   schemaVersion: 1;
   decision: ViewerAnalyticsConsentDecision;
-  source: "default-deny" | "stored" | "global-privacy-control";
+  source: "tenant-default" | "default-deny" | "stored" | "global-privacy-control";
   canGrant: boolean;
   expiresAt: number | null;
   retentionDays: typeof VIEWER_ANALYTICS_CONSENT_RETENTION_DAYS;
@@ -591,6 +591,7 @@ export function applyEarlyViewerAnalyticsConsent(
   // approval. Only the current authenticated server-rendered snapshot may grant.
   const contextComplete = tenantPublicId.length > 0 && environment.length > 0 && siteSurface.length > 0;
   const tenantApprovedAnalytics = contextComplete && rawApproved.includes("analytics");
+  const tenantDefaultAnalytics = tenantApprovedAnalytics && rawEligible.includes("analytics");
   const globalPrivacyControl = win.navigator?.globalPrivacyControl === true;
 
   let stored: { decision: ViewerAnalyticsConsentDecision; expiresAt: number } | null = null;
@@ -631,12 +632,14 @@ export function applyEarlyViewerAnalyticsConsent(
   const decision: ViewerAnalyticsConsentDecision =
     globalPrivacyControl || !tenantApprovedAnalytics
       ? "denied"
-      : stored?.decision ?? "denied";
+      : stored?.decision ?? (tenantDefaultAnalytics ? "granted" : "denied");
   const source: ViewerAnalyticsConsentState["source"] = globalPrivacyControl
     ? "global-privacy-control"
     : stored
       ? "stored"
-      : "default-deny";
+      : tenantDefaultAnalytics
+        ? "tenant-default"
+        : "default-deny";
 
   const eligible = canonicalPurposes.filter(
     (purpose) =>

package/packages/public-runtime/src/integration/consent-config.ts

@@ -258,3 +258,12 @@ export function unmetConsentDependencies(
 export function emptyConsentConfig(): TenantConsentConfig {
   return { schemaVersion: CONSENT_CONFIG_SCHEMA_VERSION, purposes: [], cmp: { mode: "none" } };
 }
+
+/** Platform default when a tenant configured analytics and saved no consent override. */
+export function defaultAnalyticsConsentConfig(): TenantConsentConfig {
+  return {
+    schemaVersion: CONSENT_CONFIG_SCHEMA_VERSION,
+    purposes: [{ purpose: "analytics", legalBasis: "legitimate-interest", defaultState: "granted" }],
+    cmp: { mode: "none" },
+  };
+}

package/packages/public-runtime/src/integration/contact-sales-action-source.ts

@@ -1,5 +1,5 @@
 /**
- * The platform-owned browser binding for the two reviewed contact-sales CTAs.
+ * The platform-owned browser binding for reviewed contact-sales CTA identities.
  *
  * This is deliberately not a general interaction adapter. Both DOM identifiers and
  * the emitted semantic name are fixed below; the source reads no labels, URLs,
@@ -10,19 +10,41 @@ import { managedAnalyticsOpaqueRevision } from "./managed-analytics-value-safety
 
 /** The only reviewed CTA identities that may raise this marketing action. */
 export const CONTACT_SALES_ACTION_SOURCES = [
-  { ctaId: "cta-book-demo", logicalId: "contact-sales-book-demo" },
-  { ctaId: "contact-sales", logicalId: "contact-sales-lower" },
+  { selector: '[data-cta-id="cta-book-demo"]', logicalId: "contact-sales-book-demo" },
+  { selector: '[data-cta-id="book-demo"]', logicalId: "contact-sales-book-demo" },
+  { selector: '[data-cta-id="contact-sales"]', logicalId: "contact-sales-lower" },
+  { selector: '[data-tot-action="contact-sales"]', logicalId: "contact-sales-action" },
+  { selector: '[data-tot-action="nav-contact-sales"]', logicalId: "contact-sales-nav" },
 ] as const;
 
-const CONTACT_SALES_ACTION_NAME = "user_clicked_contact_sales_mktg" as const;
+export const CONTACT_SALES_ACTION_NAME = "user_clicked_contact_sales_mktg" as const;
+/** The reviewed action allowlist paired with this fixed platform source. */
+export const CONTACT_SALES_ACTION_REGISTRY = {
+  schemaVersion: 1,
+  actions: [{ name: CONTACT_SALES_ACTION_NAME }],
+} as const;
 const CORRELATION_TTL_MS = 60 * 60 * 1000;
+export const CONTACT_SALES_NAVIGATION_DEFER_MS = 100;
+
+export interface ContactSalesClickEvent {
+  altKey?: boolean;
+  button?: number;
+  ctrlKey?: boolean;
+  defaultPrevented?: boolean;
+  metaKey?: boolean;
+  preventDefault?(): void;
+  shiftKey?: boolean;
+}
 
 export interface ContactSalesActionElement {
-  addEventListener(type: "click", listener: () => void): void;
-  removeEventListener(type: "click", listener: () => void): void;
+  download?: string;
+  href?: string;
+  target?: string;
+  addEventListener(type: "click", listener: (event: ContactSalesClickEvent) => void): void;
+  removeEventListener(type: "click", listener: (event: ContactSalesClickEvent) => void): void;
 }
 
-/** The narrow DOM seam used only to find the two fixed platform CTA identities. */
+/** The narrow DOM seam used only to find the fixed platform CTA identities. */
 export interface ContactSalesActionDocument {
   querySelectorAll(selector: string): ArrayLike<ContactSalesActionElement>;
 }
@@ -31,10 +53,23 @@ export interface ContactSalesActionSourceOptions {
   document?: ContactSalesActionDocument;
   planRevision: string;
   now?: () => number;
+  navigate?: (href: string) => void;
+  schedule?: (callback: () => void, delayMs: number) => void;
+}
+
+function deferredNavigationHref(node: ContactSalesActionElement, event: ContactSalesClickEvent): string | undefined {
+  if (
+    event.defaultPrevented || (event.button !== undefined && event.button !== 0) ||
+    event.altKey || event.ctrlKey || event.metaKey || event.shiftKey ||
+    typeof event.preventDefault !== "function" || typeof node.href !== "string" || !node.href ||
+    (typeof node.target === "string" && node.target !== "" && node.target !== "_self") ||
+    (typeof node.download === "string" && node.download !== "")
+  ) return undefined;
+  return node.href;
 }
 
 /**
- * Bind literal `data-cta-id` values to a typed source for the managed-analytics
+ * Bind the fixed reviewed DOM identities to a typed source for the managed-analytics
  * bridge. A keyboard activation of an anchor/button produces its native `click`, so
  * it follows this same semantic path without a separate key listener.
  */
@@ -43,6 +78,7 @@ export function createContactSalesActionSource(
 ): PlatformManagedActionSource {
   const document = options.document;
   const now = options.now ?? Date.now;
+  const schedule = options.schedule ?? ((callback, delayMs) => { setTimeout(callback, delayMs); });
   const revisionId = managedAnalyticsOpaqueRevision(options.planRevision);
   let sequence = 0;
 
@@ -50,10 +86,15 @@ export function createContactSalesActionSource(
     subscribe(listener) {
       if (!document || typeof document.querySelectorAll !== "function") return () => {};
       const removals: Array<() => void> = [];
+      const bound = new Set<ContactSalesActionElement>();
       for (const source of CONTACT_SALES_ACTION_SOURCES) {
-        const nodes = document.querySelectorAll(`[data-cta-id="${source.ctaId}"]`);
+        const nodes = document.querySelectorAll(source.selector);
         for (const node of Array.from(nodes)) {
-          const emit = (): void => {
+          if (bound.has(node)) continue;
+          bound.add(node);
+          const emit = (event: ContactSalesClickEvent = {}): void => {
+            const navigationHref = options.navigate ? deferredNavigationHref(node, event) : undefined;
+            if (navigationHref) event.preventDefault?.();
             sequence += 1;
             const at = now();
             const activation: PlatformManagedActionActivation = {
@@ -66,6 +107,11 @@ export function createContactSalesActionSource(
               sequence,
             };
             listener(activation);
+            // A full-document navigation destroys the isolated GA4 iframe. Give its
+            // MessagePort one bounded turn to receive the reviewed action first.
+            if (navigationHref) {
+              schedule(() => options.navigate?.(navigationHref), CONTACT_SALES_NAVIGATION_DEFER_MS);
+            }
           };
           node.addEventListener("click", emit);
           removals.push(() => node.removeEventListener("click", emit));

package/packages/public-runtime/src/integration/csp-compiler.ts

@@ -63,9 +63,12 @@ export const INTEGRATION_CSP_PROFILES: Readonly<Record<string, CspSourceSet>> =
     "connect-src": ["https://cdn.usefathom.com"],
   },
 
-  // Google code and network authority live only in the null-origin sandbox. The
-  // parent needs no addition: base frame-src 'self' admits the versioned host.
-  "google-measurement": {},
+  // Google code and network authority live only in the isolated-origin sandbox. The
+  // hosted preview uses the dedicated tokenoftrust.store sibling. Custom-domain
+  // publication aliases are added from the validated canonical host at declaration time.
+  "google-measurement": {
+    "frame-src": ["https://analytics-frame.tokenoftrust.store"],
+  },
 
   // Meta pixel (fbevents.js). The loader is served from connect.facebook.net; the
   // pixel's collect endpoint is the facebook.com tracking origin. The tenant

package/packages/public-runtime/src/integration/governed-event-properties.ts

@@ -0,0 +1,62 @@
+/**
+ * The governed event-property set every reviewed analytics adapter attaches to
+ * every event it sends.
+ *
+ * These three values answer "whose traffic, on which surface, from which stage"
+ * — the question a merchant has to answer before any storefront number is worth
+ * reading. They are DERIVED from the renderer's own trusted context
+ * (`BrowserEnvironment` + the server-stamped tenant identity), never declared by
+ * a tenant and never read from the browser. That is the whole point: a tenant
+ * that could type its own `tenant` or `environment` could mislabel its traffic,
+ * so the adapter configuration contract bans those keys outright
+ * (`managed-analytics-api-v1.schemas.ts` FORBIDDEN_KEY_PATTERN, `secrets.ts`
+ * findForbiddenFields) and this module supplies them instead.
+ *
+ * They carry no person, device, account, or network signal, so they add nothing
+ * to the anonymous-collection posture the adapters already hold.
+ */
+import {
+  validateBrowserEnvironment,
+  type BrowserEnvironment,
+  type IntegrationEnvironment,
+  type IntegrationSiteSurface,
+} from "./environment.js";
+
+/** The exact, closed key set. Adding a key here is a reviewed platform change. */
+export const GOVERNED_EVENT_PROPERTY_KEYS = Object.freeze([
+  "tenant",
+  "environment",
+  "site_surface",
+] as const);
+
+export interface GovernedEventProperties {
+  /** The tenant's public id, e.g. `tokenoftrust.com`. Server-stamped. */
+  tenant: string;
+  /** The four-stage publication stage: `local` | `candidate` | `staged` | `live`. */
+  environment: IntegrationEnvironment;
+  /** The document surface: `storefront` | `checkout` | `admin` | `marketing`. */
+  site_surface: IntegrationSiteSurface;
+}
+
+/**
+ * Build the governed property set, or null when the context cannot be trusted.
+ *
+ * Fail-closed is deliberate and matches every other adapter gate: an adapter
+ * that cannot prove which tenant and stage an event belongs to must not label
+ * it, and a caller that gets null drops the event rather than sending it
+ * unlabelled. Mislabelled traffic is worse than absent traffic — it silently
+ * corrupts every report built on it.
+ */
+export function buildGovernedEventProperties(
+  environment: BrowserEnvironment,
+  tenantPublicId: string,
+): GovernedEventProperties | null {
+  const validated = validateBrowserEnvironment(environment);
+  if (!validated.ok) return null;
+  if (typeof tenantPublicId !== "string" || tenantPublicId.length === 0) return null;
+  return Object.freeze({
+    tenant: tenantPublicId,
+    environment: validated.value.environment,
+    site_surface: validated.value.siteSurface,
+  });
+}

package/packages/public-runtime/src/integration/index.ts

@@ -59,6 +59,7 @@ export * from "./platform-adapters.js";
 export * from "./native-amplitude.js";
 export * from "./native-ga4.js";
 export * from "./native-ga4-sandbox.js";
+export * from "./native-ga4-sandbox-asset.mjs";
 export * from "./platform-adapter-runtime.js";
 export * from "./render-phases.js";
 export * from "./interim-bridge.js";

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -16,7 +16,7 @@
  * constructs bundled platform code with host-owned capabilities. Every other entry goes
  * through the authority-tier loader: it loads ONLY an `elevated-parent` entry (whose
  * honest, review-only contract IS arbitrary parent-document JavaScript) and REFUSES every
- * other tier. A reviewed registry entry may construct its own null-origin iframe and
+ * other tier. A reviewed registry entry may construct its own isolated-origin iframe and
  * private typed MessagePort; arbitrary `sandbox`-tier entry modules remain refused by
  * the parent-realm loader, so their isolation is never silently downgraded. Loading is
  * also consent-gated: the binding reads
@@ -42,7 +42,7 @@ import type { NavigationCompletedEvent, NavigationKind } from "./events.js";
 import { CommerceEventBroker } from "./commerce-broker.js";
 import { validateBrowserEnvironment, BROWSER_ENVIRONMENT_GLOBAL, type BrowserEnvironment } from "./environment.js";
 import { makePlatformAdapterRuntimeLoader } from "./platform-adapter-runtime.js";
-import { NATIVE_GA4_SANDBOX_URL, type NativeGa4Transport } from "./native-ga4.js";
+import { resolveNativeGa4SandboxUrl, type NativeGa4Transport } from "./native-ga4.js";
 import {
   createBrowserNativeGa4SandboxHost,
   createNativeGa4SandboxTransport,
@@ -51,6 +51,7 @@ import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js
 import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
 import { managedAnalyticsOpaqueRevision } from "./managed-analytics-value-safety.js";
 import {
+  CONTACT_SALES_ACTION_REGISTRY,
   createContactSalesActionSource,
   type ContactSalesActionDocument,
 } from "./contact-sales-action-source.js";
@@ -68,7 +69,7 @@ export const LIFECYCLE_NAVIGATION_SINK_GLOBAL = "__TOT_INTEGRATION_NAVIGATION__"
 
 /** The narrow slice of `window` the binding depends on — structural, for edge-safe typing. */
 export interface LifecycleWindow {
-  location: { pathname: string; search: string; hash: string; href: string };
+  location: { pathname: string; search: string; hash: string; href: string; assign?: (href: string) => void };
   addEventListener(type: string, listener: (event: unknown) => void): void;
   fetch?: typeof fetch;
   /**
@@ -118,7 +119,7 @@ export interface BootLifecycleOptions {
   fetchCapability?: typeof fetch;
   /** Entry import capability; injectable for tests and non-browser hosts. */
   importModule?: (url: string) => Promise<unknown>;
-  /** Reviewed null-origin GA4 transport; injectable for DOM-free tests. */
+  /** Reviewed isolated-origin GA4 transport; injectable for DOM-free tests. */
   nativeGa4Transport?: NativeGa4Transport;
 }
 
@@ -207,6 +208,7 @@ function makeDocumentCommerceBroker(
     },
     source: `//${descriptor.tenantPublicId}`,
     consentSnapshot: getConsentSnapshot,
+    tenantActionRegistry: CONTACT_SALES_ACTION_REGISTRY,
   });
 }
 
@@ -242,7 +244,7 @@ function documentPageView(
   const id = `pageview-${managedAnalyticsOpaqueRevision(descriptor.planRevision)}`;
   return {
     logicalId: id,
-    path: win.location.pathname,
+    path: canonicalDocumentPath(win.location.pathname, descriptor.tenantPublicId),
     correlation: {
       id,
       expiresAt: new Date(now() + PAGE_VIEW_CORRELATION_TTL_MS).toISOString(),
@@ -251,6 +253,28 @@ function documentPageView(
   };
 }
 
+/**
+ * Project immutable preview wrapper routes back to the tenant path they render.
+ * The wrapper contains a commit SHA, which is both non-canonical and deliberately
+ * rejected by the analytics value-safety boundary. Public/live routes pass through.
+ */
+export function canonicalDocumentPath(pathname: string, tenantPublicId: string): string {
+  const segments = pathname.split("/");
+  const previewIndex = segments[1] === tenantPublicId && segments[2] === "preview"
+    ? 2
+    : segments[1] === "preview"
+      ? 1
+      : -1;
+  if (
+    previewIndex !== -1 &&
+    (segments[previewIndex + 1] === "staged" || segments[previewIndex + 1] === "rev") &&
+    /^[0-9a-f]{40,64}$/i.test(segments[previewIndex + 2] ?? "")
+  ) {
+    return `/${segments.slice(previewIndex + 3).join("/")}`;
+  }
+  return pathname;
+}
+
 function readDescriptor(win: LifecycleWindow): IntegrationBootDescriptor | null {
   const descriptor = win[INTEGRATION_PLAN_GLOBAL];
   if (!descriptor || typeof descriptor !== "object") return null;
@@ -326,7 +350,7 @@ export function bootIntegrationLifecycle(
       }
       return createNativeGa4SandboxTransport(
         createBrowserNativeGa4SandboxHost(document, MessageChannel),
-        NATIVE_GA4_SANDBOX_URL,
+        resolveNativeGa4SandboxUrl(win.location.href),
       );
     },
   });
@@ -364,6 +388,10 @@ export function bootIntegrationLifecycle(
               : undefined,
             planRevision: descriptor.planRevision,
             now: options.now ?? Date.now,
+            navigate: (href) => {
+              if (typeof win.location.assign === "function") win.location.assign(href);
+              else win.location.href = href;
+            },
           }),
         }),
       pageView: () => documentPageView(win, descriptor, options.now ?? Date.now),

package/packages/public-runtime/src/integration/lifecycle-host-asset.d.mts

@@ -1,3 +1,5 @@
 /** Types for the dual-consumer (`.ts` engine + `.mjs` build plugin) host-asset path. */
 export declare const LIFECYCLE_HOST_ASSET_PATH: string;
 export declare const LIFECYCLE_HOST_ASSET_URL: string;
+export declare const LIFECYCLE_HOST_COMPATIBILITY_ASSET_PATHS: readonly string[];
+export declare const LIFECYCLE_HOST_COMPATIBILITY_ASSET_URLS: readonly string[];

package/packages/public-runtime/src/integration/lifecycle-host-asset.mjs

@@ -3,15 +3,29 @@
  *
  * It lives in a `.mjs` module because it has TWO consumers that cannot share a `.ts`
  * one: the render engine (`render-phases.ts`) that emits the `<script src>`, and the
- * build plugin (`apps/storefront/build-plugins/lifecycle-host-asset.mjs`) that produces
+ * build integration (`apps/storefront/integrations/lifecycle-host-asset.mjs`) that produces
  * the file at that exact path. One source of truth, so the tag and the artifact cannot
  * disagree — a mismatch would leave every static tenant page with plan data and no host,
  * which fails silently in exactly the way it is not allowed to.
  *
- * The path is version-pinned (`/v1/`) like a platform adapter entry, so a future host
+ * The path is version-pinned (`/v3/`) like a platform adapter entry, so a future host
  * with a different boot contract ships alongside rather than replacing this one.
  */
-export const LIFECYCLE_HOST_ASSET_PATH = "platform/lifecycle/v1/boot.mjs";
+export const LIFECYCLE_HOST_ASSET_PATH = "platform/lifecycle/v3/boot.mjs";
+
+/**
+ * Earlier immutable URLs that must keep serving the current host bytes during a
+ * version transition. Cached HTML may still reference one of these paths after a
+ * pointer flip, so dropping it would turn a cache refresh into a lifecycle 404.
+ */
+export const LIFECYCLE_HOST_COMPATIBILITY_ASSET_PATHS = Object.freeze([
+  "platform/lifecycle/v2/boot.mjs",
+]);
 
 /** The root-absolute, same-origin URL the served markup references. */
 export const LIFECYCLE_HOST_ASSET_URL = `/${LIFECYCLE_HOST_ASSET_PATH}`;
+
+/** Root-absolute compatibility URLs emitted alongside the current URL. */
+export const LIFECYCLE_HOST_COMPATIBILITY_ASSET_URLS = Object.freeze(
+  LIFECYCLE_HOST_COMPATIBILITY_ASSET_PATHS.map((path) => `/${path}`),
+);

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

@@ -20,6 +20,10 @@ import {
   type IntegrationEnvironment,
 } from "./environment.js";
 import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+import {
+  buildGovernedEventProperties,
+  type GovernedEventProperties,
+} from "./governed-event-properties.js";
 import type {
   IntegrationEventSubscribe,
   IntegrationLifecycleContext,
@@ -47,7 +51,7 @@ export interface AmplitudeHttpEvent {
   event_type: "page_view" | (typeof APPROVED_MARKETING_ACTION_NAMES)[number];
   device_id: typeof ANONYMOUS_DEVICE_ID;
   insert_id: string;
-  event_properties: { page_path: string } | Record<string, never>;
+  event_properties: GovernedEventProperties & { page_path?: string };
 }
 
 export const AMPLITUDE_DEDUPE_CAPACITY = 512 as const;
@@ -127,6 +131,11 @@ export function mapCommerceEventToAmplitude(
   ) return null;
   if (!event.consent.eligiblePurposes.includes("analytics")) return null;
 
+  // Derived from the same trusted context the equality check above just proved
+  // this event agrees with, so labelling can never disagree with admission.
+  const governed = buildGovernedEventProperties(environmentResult.value, tenantPublicId);
+  if (!governed) return null;
+
   const base = {
     device_id: ANONYMOUS_DEVICE_ID,
     insert_id: eventDedupeKey(event),
@@ -137,12 +146,12 @@ export function mapCommerceEventToAmplitude(
     return {
       ...base,
       event_type: name as (typeof APPROVED_MARKETING_ACTION_NAMES)[number],
-      event_properties: {},
+      event_properties: { ...governed },
     };
   }
   const path = event.data["path"];
   if (!isSafePagePath(path)) return null;
-  return { ...base, event_type: "page_view", event_properties: { page_path: path } };
+  return { ...base, event_type: "page_view", event_properties: { ...governed, page_path: path } };
 }
 
 export interface RegisterAmplitudeHttpDestinationInput {

package/packages/public-runtime/src/integration/native-ga4-sandbox-asset.d.mts

@@ -1,2 +1,4 @@
 export const NATIVE_GA4_SANDBOX_ASSET_PATH: "platform/google-measurement/v2/sandbox.html";
 export const NATIVE_GA4_SANDBOX_ASSET_URL: "/platform/google-measurement/v2/sandbox.html";
+export const NATIVE_GA4_SANDBOX_ORIGIN: "https://analytics-frame.tokenoftrust.store";
+export function resolveNativeGa4SandboxUrl(parentHref: string): string;

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

@@ -1,3 +1,37 @@
-/** Stable provider-neutral artifact path for the reviewed GA4 null-origin sandbox. */
+/** Stable provider-neutral artifact path for the reviewed GA4 transport frame. */
 export const NATIVE_GA4_SANDBOX_ASSET_PATH = "platform/google-measurement/v2/sandbox.html";
 export const NATIVE_GA4_SANDBOX_ASSET_URL = `/${NATIVE_GA4_SANDBOX_ASSET_PATH}`;
+export const NATIVE_GA4_SANDBOX_ORIGIN = "https://analytics-frame.tokenoftrust.store";
+
+/**
+ * Keep Google tag execution on a real, isolated origin. An opaque sandbox origin makes
+ * gtag.js load successfully but silently suppresses every collection request. Production
+ * uses a dedicated no-auth hostname for hosted surfaces and the tenant's paired apex/www
+ * publication alias for custom domains. Local development uses an analytics.localhost
+ * sibling while retaining the current dev-server port.
+ */
+export function resolveNativeGa4SandboxUrl(parentHref) {
+  const parent = new URL(parentHref);
+  if (parent.hostname === "localhost" || parent.hostname.endsWith(".localhost")) {
+    const sandbox = new URL(NATIVE_GA4_SANDBOX_ASSET_URL, parent);
+    sandbox.hostname = "analytics.localhost";
+    return sandbox.href;
+  }
+  if (parent.hostname === "tokenoftrust.store" || parent.hostname.endsWith(".tokenoftrust.store")) {
+    return new URL(NATIVE_GA4_SANDBOX_ASSET_URL, NATIVE_GA4_SANDBOX_ORIGIN).href;
+  }
+  // A static publication verification alias is deliberately not the tenant's
+  // canonical apex/www pair. Its frame must still share the tenant's site: gtag.js
+  // loads but suppresses collection from a third-party frame. The corresponding
+  // analytics-frame hostname is provisioned as a Cloudflare-for-SaaS custom host.
+  if (parent.hostname.startsWith("published.")) {
+    const sandbox = new URL(NATIVE_GA4_SANDBOX_ASSET_URL, parent);
+    sandbox.hostname = `analytics-frame.${parent.hostname.slice("published.".length)}`;
+    return sandbox.href;
+  }
+  const sandbox = new URL(NATIVE_GA4_SANDBOX_ASSET_URL, parent);
+  sandbox.hostname = parent.hostname.startsWith("www.")
+    ? parent.hostname.slice("www.".length)
+    : `www.${parent.hostname}`;
+  return sandbox.href;
+}

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

@@ -9,6 +9,7 @@ import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-val
 
 const MEASUREMENT_ID = /^G-[A-Z0-9]{4,20}$/;
 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 APPROVED_ACTIONS: ReadonlySet<string> = new Set(APPROVED_MARKETING_ACTION_NAMES);
 
 function plainRecord(value: unknown): Record<string, unknown> | null {
@@ -44,6 +45,20 @@ function validIds(value: unknown): value is string[] {
     value.every((id) => typeof id === "string" && MEASUREMENT_ID.test(id)) && new Set(value).size === value.length;
 }
 
+/**
+ * Governed labelling arrives across a hostile boundary, so it is re-validated
+ * here rather than trusted: the exact three keys, each a bare token. `tenant`
+ * is a public host id and the other two are closed enums the parent derives, so
+ * nothing here can smuggle a value gtag would treat as anything but a label.
+ */
+function validGovernedProperties(value: unknown): value is Record<string, string> {
+  const record = plainRecord(value);
+  if (!record || !exactKeys(record, ["tenant", "environment", "site_surface"])) return false;
+  return Object.values(record).every((item) =>
+    typeof item === "string" && GOVERNED_VALUE.test(item) &&
+    !resemblesManagedAnalyticsProtectedValue(item));
+}
+
 function validCampaign(value: unknown): value is Record<string, string> {
   const record = plainRecord(value);
   if (!record || !exactKeys(record, ["source", "medium", "campaign", "term", "content"], [])) return false;
@@ -64,11 +79,11 @@ export function startNativeGa4Sandbox(win: NativeGa4SandboxRuntimeWindow, doc: D
   const bind = (event: MessageEvent): void => {
     try {
       const data = plainRecord(event.data);
-      const ownOrigin = new URL(win.location.href).origin;
       if (
-        bound || event.source !== win.parent || event.origin !== ownOrigin || event.ports.length !== 1 ||
-        !data || !exactKeys(data, ["protocol", "type"]) ||
+        bound || event.source !== win.parent || event.ports.length !== 1 ||
+        !data || !exactKeys(data, ["protocol", "type", "parentOrigin"]) ||
         data["protocol"] !== NATIVE_GA4_SANDBOX_PROTOCOL || data["type"] !== "bind"
+        || !validOrigin(data["parentOrigin"]) || event.origin !== data["parentOrigin"]
       ) return;
       bound = true;
       win.removeEventListener("message", bind);
@@ -85,9 +100,9 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
   let active = false;
   let disposed = false;
   let canonicalOrigin = "";
-  let currentGroup = "";
+  let currentDestinations: string[] = [];
+  let governedProperties: Record<string, string> = {};
   let lastPageLocation = "";
-  let generation = 0;
   let tagLoaded = false;
 
   const dataLayer: unknown[] = [];
@@ -99,13 +114,16 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
 
   const configure = (message: Record<string, unknown>): void => {
     if (
-      !exactKeys(message, ["schemaVersion", "type", "destinationIds", "canonicalOrigin"]) ||
+      !exactKeys(message, ["schemaVersion", "type", "destinationIds", "canonicalOrigin", "analyticsConsent", "governedProperties"]) ||
       message["schemaVersion"] !== 1 || message["type"] !== "configure" ||
-      !validIds(message["destinationIds"]) || !validOrigin(message["canonicalOrigin"])
+      message["analyticsConsent"] !== "granted" ||
+      !validIds(message["destinationIds"]) || !validOrigin(message["canonicalOrigin"]) ||
+      !validGovernedProperties(message["governedProperties"])
     ) return;
     const ids = message["destinationIds"];
     canonicalOrigin = message["canonicalOrigin"];
-    currentGroup = `tot_storefront_${++generation}`;
+    governedProperties = { ...message["governedProperties"] };
+    currentDestinations = [...ids];
     lastPageLocation = "";
     active = true;
 
@@ -119,9 +137,13 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
       });
       gtag("js", new Date());
     }
+    // This sandbox is created and configured only after the parent lifecycle's
+    // platform consent gate grants analytics. Mirror that granted state into Google's
+    // consent mode; leaving its default denied suppresses the explicit page_view that
+    // follows even though the platform correctly admitted it.
+    gtag("consent", "update", { analytics_storage: message["analyticsConsent"] });
     for (const id of ids) {
       gtag("config", id, {
-        groups: currentGroup,
         send_page_view: false,
         allow_google_signals: false,
         allow_ad_personalization_signals: false,
@@ -148,7 +170,7 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
       const pageLocation = `${canonicalOrigin}${message["path"]}`;
       lastPageLocation = pageLocation;
       const params: Record<string, unknown> = {
-        send_to: currentGroup,
+        ...governedProperties,
         page_location: pageLocation,
         page_path: message["path"],
       };
@@ -160,7 +182,9 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
           if (campaign[key] !== undefined) params[`campaign_${ga4Key}`] = campaign[key];
         }
       }
-      gtag("event", "page_view", params);
+      for (const id of currentDestinations) {
+        gtag("event", "page_view", { ...params, send_to: id });
+      }
       return;
     }
     if (message["type"] === "action") {
@@ -169,7 +193,14 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
         typeof message["name"] !== "string" || !APPROVED_ACTIONS.has(message["name"]) ||
         message["pageLocation"] !== lastPageLocation || !lastPageLocation
       ) return;
-      gtag("event", message["name"], { send_to: currentGroup, page_location: lastPageLocation });
+      for (const id of currentDestinations) {
+        gtag("event", message["name"], {
+          ...governedProperties,
+          send_to: id,
+          page_location: lastPageLocation,
+          transport_type: "beacon",
+        });
+      }
     }
   };
 
@@ -181,6 +212,7 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
       if (message["type"] === "disable") {
         if (exactKeys(message, ["schemaVersion", "type"]) && message["schemaVersion"] === 1) {
           active = false;
+          currentDestinations = [];
           lastPageLocation = "";
         }
         return;
@@ -189,6 +221,7 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
         if (exactKeys(message, ["schemaVersion", "type"]) && message["schemaVersion"] === 1) {
           active = false;
           disposed = true;
+          currentDestinations = [];
           lastPageLocation = "";
           port.close();
         }