@tokenoftrust/storefront-runner 2.0.30 → 2.0.32

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

@@ -92,13 +92,16 @@ export interface ConsentDestination {
 
 /**
  * The versioned, browser-safe consent snapshot — the single value client and server
- * destinations filter against. `eligiblePurposes` is in canonical purpose order and
- * always contains `essential`. `unknownState` is always `"block"` (fail closed).
+ * destinations filter against. `eligiblePurposes` and `approvedPurposes` are in
+ * canonical purpose order and always contain `essential`; approval is deliberately
+ * separate from current viewer eligibility. `unknownState` is always `"block"`.
  */
 export interface ConsentSnapshot {
   schemaVersion: typeof CONSENT_SNAPSHOT_SCHEMA_VERSION;
   snapshotId: string;
   eligiblePurposes: ConsentPurpose[];
+  /** Purposes the tenant approved to exist, whether or not this viewer granted them. */
+  approvedPurposes: ConsentPurpose[];
   unknownState: "block";
 }
 
@@ -113,20 +116,32 @@ function fnv1a32Hex(input: string): string {
   return (h >>> 0).toString(16).padStart(8, "0");
 }
 
-/** Content-addressed snapshot id: identical eligibility → identical id on client and server. */
-function computeSnapshotId(eligible: readonly ConsentPurpose[]): string {
-  return `cs1-${fnv1a32Hex(`${CONSENT_SNAPSHOT_SCHEMA_VERSION}:${eligible.join(",")}`)}`;
+/** Content-addressed snapshot id: identical eligibility + approval → identical id on client and server. */
+function computeSnapshotId(
+  eligible: readonly ConsentPurpose[],
+  approved: readonly ConsentPurpose[],
+): string {
+  return `cs${CONSENT_SNAPSHOT_SCHEMA_VERSION}-${fnv1a32Hex(
+    `${CONSENT_SNAPSHOT_SCHEMA_VERSION}:${eligible.join(",")}:${approved.join(",")}`,
+  )}`;
 }
 
 /** Build a snapshot from an eligible set, forcing `essential` on and canonicalizing order. */
-function makeSnapshot(eligible: Iterable<ConsentPurpose>): ConsentSnapshot {
+function makeSnapshot(
+  eligible: Iterable<ConsentPurpose>,
+  approved: Iterable<ConsentPurpose> = eligible,
+): ConsentSnapshot {
   const set = new Set<ConsentPurpose>(eligible);
   set.add(ESSENTIAL);
+  const approvedSet = new Set<ConsentPurpose>(approved);
+  approvedSet.add(ESSENTIAL);
   const eligiblePurposes = CONSENT_PURPOSES.filter((p) => set.has(p));
+  const approvedPurposes = CONSENT_PURPOSES.filter((p) => approvedSet.has(p));
   return {
     schemaVersion: CONSENT_SNAPSHOT_SCHEMA_VERSION,
-    snapshotId: computeSnapshotId(eligiblePurposes),
+    snapshotId: computeSnapshotId(eligiblePurposes, approvedPurposes),
     eligiblePurposes,
+    approvedPurposes,
     unknownState: "block",
   };
 }
@@ -137,7 +152,7 @@ function makeSnapshot(eligible: Iterable<ConsentPurpose>): ConsentSnapshot {
  * granted. This is what precedes every vendor loader.
  */
 export function defaultConsentSnapshot(): ConsentSnapshot {
-  return makeSnapshot([ESSENTIAL]);
+  return makeSnapshot([ESSENTIAL], [ESSENTIAL]);
 }
 
 /**
@@ -204,9 +219,8 @@ export function serializeConsentSnapshot(snapshot: ConsentSnapshot): string {
 
 /**
  * Parse a serialized snapshot fail-closed: an unknown schema version, a non-block
- * unknown state, an unknown purpose, a missing `essential`, or an id that does not
- * match the eligible set yields `null` — a caller cannot smuggle in a forged or
- * tampered snapshot.
+ * unknown state, an unknown purpose, a missing `essential`, eligibility outside the
+ * tenant-approved set, or an id that does not match both sets yields `null`.
  */
 export function parseConsentSnapshot(raw: unknown): ConsentSnapshot | null {
   let obj: unknown = raw;
@@ -230,7 +244,14 @@ export function parseConsentSnapshot(raw: unknown): ConsentSnapshot | null {
   }
   const eligible = CONSENT_PURPOSES.filter((p) => (eligibleRaw as string[]).includes(p));
   if (!eligible.includes(ESSENTIAL)) return null;
-  const canonical = makeSnapshot(eligible);
+  const approvedRaw = s["approvedPurposes"];
+  if (!Array.isArray(approvedRaw)) return null;
+  for (const p of approvedRaw) {
+    if (typeof p !== "string" || !known.has(p)) return null;
+  }
+  const approved = CONSENT_PURPOSES.filter((p) => (approvedRaw as string[]).includes(p));
+  if (!approved.includes(ESSENTIAL) || eligible.some((p) => !approved.includes(p))) return null;
+  const canonical = makeSnapshot(eligible, approved);
   if (canonical.snapshotId !== s["snapshotId"]) return null;
   return canonical;
 }
@@ -423,7 +444,7 @@ export class ConsentBroker {
 
   private compute(): ConsentSnapshot {
     const eligible = CONSENT_PURPOSES.filter((p) => this.effective(p) === "granted");
-    return makeSnapshot(eligible);
+    return makeSnapshot(eligible, [ESSENTIAL, ...this.approved.keys()]);
   }
 
   private update(): ConsentSnapshot {
@@ -450,3 +471,339 @@ 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.
+ */
+
+export const VIEWER_ANALYTICS_CONSENT_STORAGE_KEY = "tot.viewer-analytics-consent.v1";
+export const VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL = "__TOT_VIEWER_ANALYTICS_CONSENT__";
+export const VIEWER_ANALYTICS_CONSENT_CHANGE_EVENT = "tot:viewer-analytics-consent-changed";
+export const VIEWER_ANALYTICS_CONSENT_RETENTION_DAYS = 180;
+export const VIEWER_ANALYTICS_REGION_POLICY = "universal-opt-in" as const;
+
+export type ViewerAnalyticsConsentDecision = "granted" | "denied";
+
+export interface ViewerAnalyticsConsentState {
+  schemaVersion: 1;
+  decision: ViewerAnalyticsConsentDecision;
+  source: "default-deny" | "stored" | "global-privacy-control";
+  canGrant: boolean;
+  expiresAt: number | null;
+  retentionDays: typeof VIEWER_ANALYTICS_CONSENT_RETENTION_DAYS;
+  regionPolicy: typeof VIEWER_ANALYTICS_REGION_POLICY;
+  tenantPublicId: string;
+  environment: string;
+  siteSurface: string;
+}
+
+interface ViewerConsentWindow {
+  navigator?: { globalPrivacyControl?: boolean };
+  localStorage?: {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+  };
+  document?: Document;
+  addEventListener?: (type: string, listener: (event: { key?: string | null }) => void) => void;
+  dispatchEvent?: (event: Event) => boolean;
+  CustomEvent?: typeof CustomEvent;
+  [key: string]: unknown;
+}
+
+/**
+ * Apply the effective viewer decision before any analytics loader runs.
+ *
+ * This function is deliberately closure-free: its runtime source is also serialized
+ * into the renderer's early-head script, keeping the tested function and emitted boot
+ * byte-for-byte one implementation rather than two drifting copies.
+ */
+export function applyEarlyViewerAnalyticsConsent(
+  win: ViewerConsentWindow,
+  now: number = Date.now(),
+  override?: ViewerAnalyticsConsentDecision,
+): ViewerAnalyticsConsentState {
+  const consentGlobal = "__TOT_INTEGRATION_CONSENT__";
+  const planGlobal = "__TOT_INTEGRATION_PLAN__";
+  const stateGlobal = "__TOT_VIEWER_ANALYTICS_CONSENT__";
+  const storageKey = "tot.viewer-analytics-consent.v1";
+  const retentionDays = 180;
+  const retentionMs = retentionDays * 24 * 60 * 60 * 1000;
+  const canonicalPurposes = ["essential", "analytics", "marketing", "personalization"];
+
+  const current = win[consentGlobal] as {
+    schemaVersion?: unknown;
+    snapshotId?: unknown;
+    eligiblePurposes?: unknown;
+    approvedPurposes?: unknown;
+    unknownState?: unknown;
+  } | undefined;
+  const plan = win[planGlobal] as {
+    tenantPublicId?: unknown;
+    environment?: unknown;
+    siteSurface?: unknown;
+  } | undefined;
+  const candidateEligible = Array.isArray(current?.eligiblePurposes)
+    ? current.eligiblePurposes.filter((purpose): purpose is string =>
+        typeof purpose === "string" && canonicalPurposes.includes(purpose))
+    : [];
+  const candidateApproved = Array.isArray(current?.approvedPurposes)
+    ? current.approvedPurposes.filter((purpose): purpose is string =>
+        typeof purpose === "string" && canonicalPurposes.includes(purpose))
+    : [];
+  const snapshotIdFor = (eligible: readonly string[], approved: readonly string[]) => {
+    let hash = 0x811c9dc5;
+    const digestInput = `2:${eligible.join(",")}:${approved.join(",")}`;
+    for (let index = 0; index < digestInput.length; index += 1) {
+      const code = digestInput.charCodeAt(index);
+      hash = Math.imul(hash ^ (code & 0xff), 0x01000193);
+      hash = Math.imul(hash ^ ((code >> 8) & 0xff), 0x01000193);
+    }
+    return `cs2-${(hash >>> 0).toString(16).padStart(8, "0")}`;
+  };
+  const snapshotValid =
+    current?.schemaVersion === 2 &&
+    current.unknownState === "block" &&
+    Array.isArray(current.eligiblePurposes) &&
+    candidateEligible.length === current.eligiblePurposes.length &&
+    Array.isArray(current.approvedPurposes) &&
+    candidateApproved.length === current.approvedPurposes.length &&
+    candidateEligible.join(",") ===
+      canonicalPurposes.filter((purpose) => candidateEligible.includes(purpose)).join(",") &&
+    candidateApproved.join(",") ===
+      canonicalPurposes.filter((purpose) => candidateApproved.includes(purpose)).join(",") &&
+    candidateEligible.includes("essential") &&
+    candidateApproved.includes("essential") &&
+    candidateEligible.every((purpose) => candidateApproved.includes(purpose)) &&
+    current.snapshotId === snapshotIdFor(candidateEligible, candidateApproved);
+  const rawEligible = snapshotValid ? candidateEligible : ["essential"];
+  const rawApproved = snapshotValid ? candidateApproved : ["essential"];
+  const tenantPublicId = typeof plan?.tenantPublicId === "string" ? plan.tenantPublicId : "";
+  const environment = typeof plan?.environment === "string" ? plan.environment : "";
+  const siteSurface = typeof plan?.siteSurface === "string" ? plan.siteSurface : "";
+  const contextKey = `${tenantPublicId}:${environment}:${siteSurface}`;
+  const scopedStorageKey = `${storageKey}:${encodeURIComponent(contextKey)}`;
+  // A manifest's consentNeeds and mutable viewer state are requests, never tenant
+  // 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 globalPrivacyControl = win.navigator?.globalPrivacyControl === true;
+
+  let stored: { decision: ViewerAnalyticsConsentDecision; expiresAt: number } | null = null;
+  if (override) {
+    stored = { decision: override, expiresAt: now + retentionMs };
+  } else {
+    try {
+      const raw = win.localStorage?.getItem(scopedStorageKey);
+      if (raw) {
+        const parsed = JSON.parse(raw) as Record<string, unknown>;
+        const keys = Object.keys(parsed).sort();
+        const decidedAt = parsed["decidedAt"];
+        const expiresAt = parsed["expiresAt"];
+        const decision = parsed["decision"];
+        if (
+          keys.join(",") === "decidedAt,decision,environment,expiresAt,schemaVersion,siteSurface,tenantPublicId" &&
+          parsed["schemaVersion"] === 1 &&
+          parsed["tenantPublicId"] === tenantPublicId &&
+          parsed["environment"] === environment &&
+          parsed["siteSurface"] === siteSurface &&
+          (decision === "granted" || decision === "denied") &&
+          typeof decidedAt === "number" &&
+          Number.isFinite(decidedAt) &&
+          typeof expiresAt === "number" &&
+          Number.isFinite(expiresAt) &&
+          decidedAt <= now &&
+          expiresAt > now &&
+          expiresAt - decidedAt === retentionMs
+        ) {
+          stored = { decision, expiresAt };
+        }
+      }
+    } catch {
+      // Storage denial, malformed data, and hostile access all fail closed.
+    }
+  }
+
+  const decision: ViewerAnalyticsConsentDecision =
+    globalPrivacyControl || !tenantApprovedAnalytics
+      ? "denied"
+      : stored?.decision ?? "denied";
+  const source: ViewerAnalyticsConsentState["source"] = globalPrivacyControl
+    ? "global-privacy-control"
+    : stored
+      ? "stored"
+      : "default-deny";
+
+  const eligible = canonicalPurposes.filter(
+    (purpose) =>
+      purpose === "essential" ||
+      (purpose === "analytics"
+        ? decision === "granted" && tenantApprovedAnalytics
+        : rawEligible.includes(purpose)),
+  );
+  const approved = canonicalPurposes.filter((purpose) => rawApproved.includes(purpose));
+  win[consentGlobal] = Object.freeze({
+    schemaVersion: 2,
+    snapshotId: snapshotIdFor(eligible, approved),
+    eligiblePurposes: Object.freeze(eligible),
+    approvedPurposes: Object.freeze(approved),
+    unknownState: "block",
+  });
+
+  const state: ViewerAnalyticsConsentState = Object.freeze({
+    schemaVersion: 1,
+    decision,
+    source,
+    canGrant: tenantApprovedAnalytics && !globalPrivacyControl,
+    expiresAt: stored?.expiresAt ?? null,
+    retentionDays,
+    regionPolicy: "universal-opt-in",
+    tenantPublicId,
+    environment,
+    siteSurface,
+  });
+  win[stateGlobal] = state;
+  return state;
+}
+
+/** The exact synchronous script rendered after the plan + consent globals in `<head>`. */
+export const VIEWER_ANALYTICS_CONSENT_EARLY_BOOT_JS =
+  `(${applyEarlyViewerAnalyticsConsent.toString()})(window);`;
+
+function writeDecision(
+  win: ViewerConsentWindow,
+  decision: ViewerAnalyticsConsentDecision,
+  now: number,
+): void {
+  const retentionMs = VIEWER_ANALYTICS_CONSENT_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+  try {
+    const plan = win["__TOT_INTEGRATION_PLAN__"] as {
+      tenantPublicId?: unknown;
+      environment?: unknown;
+      siteSurface?: unknown;
+    } | undefined;
+    const tenantPublicId = typeof plan?.tenantPublicId === "string" ? plan.tenantPublicId : "";
+    const environment = typeof plan?.environment === "string" ? plan.environment : "";
+    const siteSurface = typeof plan?.siteSurface === "string" ? plan.siteSurface : "";
+    const contextKey = `${tenantPublicId}:${environment}:${siteSurface}`;
+    win.localStorage?.setItem(
+      `${VIEWER_ANALYTICS_CONSENT_STORAGE_KEY}:${encodeURIComponent(contextKey)}`,
+      JSON.stringify({
+        schemaVersion: 1,
+        decision,
+        decidedAt: now,
+        expiresAt: now + retentionMs,
+        tenantPublicId,
+        environment,
+        siteSurface,
+      }),
+    );
+  } catch {
+    // The in-memory decision still applies to this document; the next load fails closed.
+  }
+}
+
+function notifyViewerAnalyticsConsentChanged(
+  win: ViewerConsentWindow,
+  state: ViewerAnalyticsConsentState,
+): void {
+  const EventCtor = win.CustomEvent ?? (typeof CustomEvent === "function" ? CustomEvent : undefined);
+  if (EventCtor && win.dispatchEvent) {
+    win.dispatchEvent(new EventCtor(VIEWER_ANALYTICS_CONSENT_CHANGE_EVENT, {
+      detail: Object.freeze({ decision: state.decision }),
+    }));
+  }
+
+  const lifecycle = win["__TOT_INTEGRATION_LIFECYCLE__"] as
+    | { update?: (reason: "consent-changed") => unknown }
+    | undefined;
+  try {
+    const updated = lifecycle?.update?.("consent-changed");
+    if (updated && typeof (updated as Promise<unknown>).catch === "function") {
+      void (updated as Promise<unknown>).catch(() => {});
+    }
+  } catch {
+    // Consent state is already deny/grant; an integration cannot make the control fail.
+  }
+}
+
+/** Apply a viewer action, update every broker reader, and notify the live lifecycle. */
+export function setViewerAnalyticsConsent(
+  win: ViewerConsentWindow,
+  decision: ViewerAnalyticsConsentDecision,
+  now: number = Date.now(),
+): ViewerAnalyticsConsentState {
+  if (!(decision === "granted" && win.navigator?.globalPrivacyControl === true)) {
+    writeDecision(win, decision, now);
+  }
+  const state = applyEarlyViewerAnalyticsConsent(win, now, decision);
+  notifyViewerAnalyticsConsentChanged(win, state);
+  return state;
+}
+
+function renderControlState(root: HTMLElement, state: ViewerAnalyticsConsentState): void {
+  const status = root.querySelector<HTMLElement>("[data-tot-analytics-consent-status]");
+  const grant = root.querySelector<HTMLButtonElement>('[data-tot-analytics-consent-decision="granted"]');
+  const deny = root.querySelector<HTMLButtonElement>('[data-tot-analytics-consent-decision="denied"]');
+  if (status) {
+    status.textContent = state.source === "global-privacy-control"
+      ? "Analytics off — Global Privacy Control"
+      : state.decision === "granted"
+        ? "Analytics on"
+        : "Analytics off";
+  }
+  if (grant) {
+    grant.disabled = !state.canGrant || state.decision === "granted";
+    grant.setAttribute("aria-pressed", String(state.decision === "granted"));
+  }
+  if (deny) {
+    deny.disabled = state.decision === "denied";
+    deny.setAttribute("aria-pressed", String(state.decision === "denied"));
+  }
+}
+
+/** Bind the renderer-owned control once; safe when a document contains no analytics plan. */
+export function bootViewerAnalyticsConsentControl(
+  win: ViewerConsentWindow,
+  now: () => number = Date.now,
+): void {
+  const roots = win.document?.querySelectorAll<HTMLElement>("[data-tot-analytics-consent-control]");
+  const current = (win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined) ??
+    applyEarlyViewerAnalyticsConsent(win, now());
+  roots?.forEach((root) => {
+    renderControlState(root, current);
+    if (root.dataset["totAnalyticsConsentBound"] === "true") return;
+    root.dataset["totAnalyticsConsentBound"] = "true";
+    root.addEventListener("click", (event) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      const button = target.closest<HTMLButtonElement>("[data-tot-analytics-consent-decision]");
+      const decision = button?.dataset["totAnalyticsConsentDecision"];
+      if (decision !== "granted" && decision !== "denied") return;
+      renderControlState(root, setViewerAnalyticsConsent(win, decision, now()));
+    });
+  });
+
+  const storageBoundGlobal = "__TOT_VIEWER_ANALYTICS_CONSENT_STORAGE_BOUND__";
+  if (win.addEventListener && win[storageBoundGlobal] !== true) {
+    win[storageBoundGlobal] = true;
+    win.addEventListener("storage", (event) => {
+      // `key === null` is the browser signal for localStorage.clear(). It clears
+      // this context too, so recompute to default-deny and notify immediately.
+      if (event.key !== null && !event.key?.startsWith(`${VIEWER_ANALYTICS_CONSENT_STORAGE_KEY}:`)) return;
+      const next = applyEarlyViewerAnalyticsConsent(win, now());
+      roots?.forEach((root) => renderControlState(root, next));
+      notifyViewerAnalyticsConsentChanged(win, next);
+    });
+  }
+}
+
+/** Browser entry used by the shared lifecycle host asset. */
+export function bootViewerAnalyticsConsentFromDocument(): void {
+  if (typeof window === "undefined") return;
+  bootViewerAnalyticsConsentControl(window as unknown as ViewerConsentWindow);
+}

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

@@ -63,12 +63,9 @@ export const INTEGRATION_CSP_PROFILES: Readonly<Record<string, CspSourceSet>> =
     "connect-src": ["https://cdn.usefathom.com"],
   },
 
-  // Native Google Analytics / Ads measurement. The adapter sends reviewed event
-  // payloads only to Google's measurement endpoints; it does not load a remote
-  // browser container. Every origin is exact and platform-owned.
-  "google-measurement": {
-    "connect-src": ["https://www.google-analytics.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": {},
 
   // 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/events.ts

@@ -56,7 +56,10 @@ import {
 import { INTEGRATION_ENVIRONMENTS, INTEGRATION_SITE_SURFACES } from "./environment.js";
 import type { IntegrationEnvironment, IntegrationSiteSurface } from "./environment.js";
 import { findForbiddenFields } from "./secrets.js";
-import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+import {
+  resemblesManagedAnalyticsPii,
+  resemblesManagedAnalyticsProtectedValue,
+} from "./managed-analytics-value-safety.js";
 
 /**
  * The reserved commerce event taxonomy. Every accepted type is here; an unknown
@@ -348,9 +351,6 @@ function validateLineItems(parent: Record<string, unknown>, v: Violations, path:
 
 const UTM_FIELDS = ["source", "medium", "campaign", "term", "content"] as const;
 const SAFE_UTM_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
-const PROTECTED_ATTRIBUTION_VALUE =
-  /(?:@|\d{7,}|(?:^|[._~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[._~-]))/i;
-
 function validatePageAttribution(parent: Record<string, unknown>, v: Violations): void {
   const attribution = childObject(parent, "attribution", v, "data");
   if (!attribution) return;
@@ -403,7 +403,7 @@ function validatePageAttribution(parent: Record<string, unknown>, v: Violations)
             `UTM ${key} must be a 1-128 character opaque campaign token.`,
           );
         }
-        if (value !== undefined && PROTECTED_ATTRIBUTION_VALUE.test(value)) {
+        if (value !== undefined && resemblesManagedAnalyticsProtectedValue(value)) {
           v.add(
             `data.attribution.utm.${key}`,
             "protected_value",

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

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

package/packages/public-runtime/src/integration/interaction-tracking-gate.ts

@@ -13,8 +13,7 @@
  *     ({@link isPurposeEligible}, `consent-broker.ts`). A missing or tampered
  *     `window.__TOT_INTEGRATION_CONSENT__` global fails closed to the
  *     default-deny snapshot, same as every other consumer of that global
- *     (`lifecycle-boot.ts`, the Cloudflare Web Analytics loader in
- *     `Layout.astro`).
+ *     (`lifecycle-boot.ts` and the managed analytics adapters).
  *   - ENVIRONMENT: the renderer-published four-stage environment
  *     (`resolveBrowserEnvironment`, `environment.ts`) must resolve AND must not
  *     be `candidate`. A per-change candidate render is a preview — it is never

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

@@ -16,11 +16,10 @@
  * 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 `sandbox`-tier entry —
- * whose contract is a null-origin iframe reachable only through the typed postMessage
- * broker — is refused here and held back until the iframe host that actually isolates
- * it ships, so third-party code labeled "sandboxed" is never executed with the parent
- * authority its label does not grant. Loading is also consent-gated: the binding reads
+ * other tier. A reviewed registry entry may construct its own null-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
  * the renderer-inlined default-deny consent snapshot and holds a non-essential entry
  * back until its declared purposes are eligible. With an environment-only plan there
  * are no integrations, so the runtime boots inert and ready.
@@ -43,6 +42,11 @@ 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 {
+  createBrowserNativeGa4SandboxHost,
+  createNativeGa4SandboxTransport,
+} from "./native-ga4-sandbox.js";
 import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
 import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
 import {
@@ -53,10 +57,9 @@ import {
 /** The window property holding the single per-document lifecycle (idempotent boot guard). */
 export const LIFECYCLE_SINGLETON_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE__";
 /**
- * An optional window-published loader the entry-asset layer may install to OVERRIDE the
- * fail-closed same-origin default. It is the seam the null-origin sandboxed-iframe host
- * (the tracked F3 follow-up) installs to actually isolate a `sandbox`-tier entry; until
- * that host ships the seam is unused and the default loader refuses the sandbox tier.
+ * An optional window-published loader the entry-asset layer may install to override the
+ * fail-closed same-origin default. The default loader still refuses sandbox-tier modules;
+ * reviewed platform adapters construct any required isolation through their registry.
  */
 export const LIFECYCLE_MODULE_LOADER_GLOBAL = "__TOT_INTEGRATION_MODULE_LOADER__";
 /** An optional window-published sink for the completed-navigation event. */
@@ -114,6 +117,8 @@ 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. */
+  nativeGa4Transport?: NativeGa4Transport;
 }
 
 /**
@@ -146,11 +151,10 @@ const PARENT_REALM_TIER = "elevated-parent" as const;
  * a hardcoded vendor path. `importModule` is injected so the loader is testable without
  * a live network; it defaults to a native dynamic `import()`.
  *
- * FAIL-CLOSED BY TIER (design-partner finding F3): a parent-realm import gives the entry
+ * FAIL-CLOSED BY TIER: a parent-realm import gives the entry
  * full parent-document authority, so the loader refuses any tier but `elevated-parent`
  * BEFORE importing — a `sandbox`-tier entry throws without ever being fetched or
- * evaluated, so code labeled "sandboxed" cannot run in the parent while its isolating
- * iframe host is still the tracked follow-up. The throw is caught by the runtime's
+ * evaluated, so code labeled "sandboxed" cannot run in the parent. The throw is caught by the runtime's
  * per-integration load isolation: the entry never becomes active, the page is unaffected,
  * and every other integration still boots.
  */
@@ -163,8 +167,8 @@ export function makeSameOriginEntryLoader(
         `Refusing to load "${integration.appId}@${integration.version}" (tier ` +
           `"${integration.executionTier}") into the parent document: the same-origin loader ` +
           `only runs the "${PARENT_REALM_TIER}" tier. A "sandbox"-tier entry must run inside a ` +
-          `null-origin iframe reachable only through the typed postMessage broker; that ` +
-          `isolating host is not yet wired, so the entry is held fail-closed rather than run ` +
+          `null-origin iframe reachable only through a typed MessagePort broker, so the entry ` +
+          `is held fail-closed rather than run ` +
           `with parent-document authority its tier does not grant.`,
       );
     }
@@ -314,6 +318,16 @@ export function bootIntegrationLifecycle(
     fetchCapability: hostFetch,
     importModule: options.importModule,
     fallback: ordinaryLoader,
+    nativeGa4Transport: () => {
+      if (options.nativeGa4Transport) return options.nativeGa4Transport;
+      if (typeof document === "undefined" || typeof MessageChannel === "undefined") {
+        throw new Error("platform_adapter_ga4_sandbox_unavailable");
+      }
+      return createNativeGa4SandboxTransport(
+        createBrowserNativeGa4SandboxHost(document, MessageChannel),
+        NATIVE_GA4_SANDBOX_URL,
+      );
+    },
   });
 
   const isEligible = options.isEligible ?? defaultConsentGate(win);

package/packages/public-runtime/src/integration/lifecycle-host-entry.ts

@@ -12,5 +12,7 @@
  * self-invoking module there would boot the lifecycle on any server-side import.
  */
 import { bootIntegrationLifecycleFromDocument } from "./lifecycle-boot.js";
+import { bootViewerAnalyticsConsentFromDocument } from "./consent-broker.js";
 
+bootViewerAnalyticsConsentFromDocument();
 bootIntegrationLifecycleFromDocument();