@tokenoftrust/storefront-runner 4.9.2 → 4.10.0

package/apps/storefront/src/scheduled/contactVaultSweep.ts

@@ -0,0 +1,80 @@
+/**
+ * The hourly contact vault sweep — the Worker's `scheduled` handler body. One `now` per firing,
+ * taken from its scheduled time: purge expired order contacts and contact messages, shorten terminal
+ * orders' retention, and seal any contact message still held as legacy plaintext. Expiry predicates
+ * only; it never touches an order, audit or other row.
+ *
+ * It logs ONE structured line of counts on success and ONE fixed error code on failure — never an
+ * error message, id or row, since either could carry data. It composes orders and engagement, which
+ * no module under src/lib may do, so it lives beside the Worker entry.
+ */
+import { fromD1, type Queryable } from "@/lib/catalog/d1/catalog.js";
+import type { VaultKeyring } from "@/lib/customers/contactVault/envelope.js";
+import { purgeExpiredContactMessages, sealLegacyContactMessages } from "@/lib/engagement/contact/contactMessages.js";
+import { loadVaultKeyring } from "@/lib/orders/vault/keyringEnv.js";
+import { purgeOrderContacts, type PurgeCounts } from "@/lib/orders/vault/orderContactVault.js";
+import { readD1 } from "@/lib/publication/shared/env";
+
+export const SWEEP_LEGACY_SEAL_LIMIT = 500;
+export const CONTACT_VAULT_SWEEP_EVENT = "contact-vault-sweep";
+export const SWEEP_DB_UNAVAILABLE = "contact-vault-sweep-db-unavailable";
+export const SWEEP_FAILED = "contact-vault-sweep-failed";
+
+export interface SweepCounts {
+  orders: PurgeCounts;
+  messagesPurged: number;
+  legacySealed: number;
+  legacyRemaining: number;
+}
+
+export async function runContactVaultSweep(db: Queryable, keyring: VaultKeyring | null, now: Date): Promise<SweepCounts> {
+  if (Number.isNaN(now.getTime())) throw new Error("contact vault sweep: unreadable clock");
+  const orders = await purgeOrderContacts(db, now);
+  const messagesPurged = await purgeExpiredContactMessages(db, now);
+  const legacy = keyring
+    ? await sealLegacyContactMessages(db, keyring, now, SWEEP_LEGACY_SEAL_LIMIT)
+    : { sealed: 0, remaining: -1 };
+  return { orders, messagesPurged, legacySealed: legacy.sealed, legacyRemaining: legacy.remaining };
+}
+
+export interface ScheduledSweepDeps {
+  openDb(): Promise<Queryable | null>;
+  loadKeyring(): Promise<VaultKeyring | null>;
+  sweep(db: Queryable, keyring: VaultKeyring | null, now: Date): Promise<SweepCounts>;
+  log(line: string): void;
+  logError(line: string): void;
+}
+
+const workerDeps: ScheduledSweepDeps = {
+  openDb: async () => {
+    const d1 = await readD1("STOREFRONT_APPS_DB");
+    return d1 ? fromD1(d1) : null;
+  },
+  loadKeyring: loadVaultKeyring,
+  sweep: runContactVaultSweep,
+  log: (line) => console.log(line),
+  logError: (line) => console.error(line),
+};
+
+/** Never throws: every failure is reported as a fixed code. */
+export async function runScheduledContactVaultSweep(scheduledTime: number, deps: ScheduledSweepDeps = workerDeps): Promise<void> {
+  const fail = (error: string) => deps.logError(JSON.stringify({ event: CONTACT_VAULT_SWEEP_EVENT, error }));
+  try {
+    const db = await deps.openDb();
+    if (!db) return fail(SWEEP_DB_UNAVAILABLE);
+    const keyring = await deps.loadKeyring();
+    const counts = await deps.sweep(db, keyring, new Date(scheduledTime));
+    deps.log(JSON.stringify({
+      event: CONTACT_VAULT_SWEEP_EVENT,
+      keyringAvailable: keyring !== null,
+      ordersPurged: counts.orders.purged,
+      tombstonesRemoved: counts.orders.tombstonesRemoved,
+      ordersShortened: counts.orders.shortened,
+      messagesPurged: counts.messagesPurged,
+      legacySealed: counts.legacySealed,
+      legacyRemaining: counts.legacyRemaining,
+    }));
+  } catch {
+    fail(SWEEP_FAILED);
+  }
+}

package/apps/storefront/test/pipeline/publish-kinds.ts

@@ -40,13 +40,17 @@ type PointerRecord = Awaited<ReturnType<PointerWriter["read"]>>;
  * Production's ratios, in seconds: a CI window (45 min) outlasts the lease an evicted object waits
  * out before it resumes (10 min, here `leaseMs`), so a job resumed after an eviction is still inside
  * its window — as in production.
+ *
+ * A hotfix's stage window ends the job `stuck` when it expires, and the fault matrix answers the
+ * prebuild from a poll loop that a loaded host starves for several seconds at a time (a 30 ms sleep
+ * measured at 4–8 s on an oversubscribed machine). The window is sized well past that stall.
  */
 export const PUBLISH_HARNESS_TIMING: PublishTiming = {
   awaitWindowMs: 4_000,
   runGraceMs: 500,
   proofDelayMs: 30,
   proofProbes: { synchronous: 3, asynchronous: 5 },
-  stageWindowMs: 4_000,
+  stageWindowMs: 15_000,
   stageChecks: 3,
 };
 

package/apps/storefront/test/pipeline-faults/matrix-lib.ts

@@ -150,7 +150,7 @@ async function cloudFrontServesEarlier(t: Tenant, provider: Provider): Promise<v
 async function prerequisite(t: Tenant, kind: string, input: unknown): Promise<void> {
   const jobId = await t.submit(kind, input);
   const { job } = await drive(t, jobId);
-  if (job.state !== "succeeded") throw new Error(`setup ${kind} ended ${job.state}: ${JSON.stringify(job.error)}`);
+  if (job.state !== "succeeded") throw new Error(`setup ${kind} ended ${job.state}: ${JSON.stringify(job.error)} outcome: ${outcomeOf(job)}`);
 }
 
 async function goLive(t: Tenant, provider: Provider, sha: string, runId: string): Promise<void> {
@@ -578,6 +578,17 @@ export function overlapViolations(all: TransitionView[]): string[] {
   return [];
 }
 
+/**
+ * What the job's own outcome says about why it ended (a `JobEnded` error's reason only points at
+ * it): its reason code and message, or null when the job recorded none.
+ */
+export function outcomeOf(job: JobView): string | null {
+  const outcome = job.produces?.outcome as { reason?: unknown; message?: unknown } | undefined;
+  if (!outcome || typeof outcome !== "object") return null;
+  const parts = [outcome.reason, outcome.message].filter((p): p is string => typeof p === "string" && p.length > 0);
+  return parts.length ? parts.join(": ") : JSON.stringify(outcome);
+}
+
 function diffKeys(a: Record<string, unknown>, b: Record<string, unknown>, keys: string[]): string[] {
   return keys.filter((k) => JSON.stringify(a[k]) !== JSON.stringify(b[k]));
 }
@@ -615,7 +626,10 @@ export function convergence(cell: CellRun, base: CellRun, opts: ConvergenceOptio
   const v: string[] = [];
   const { job } = cell;
   if (job.state !== base.job.state || job.error?.code !== base.job.error?.code) {
-    v.push(`verdict: ${job.state}${job.error ? ` (${job.error.code}: ${job.error.reason})` : ""}, unfaulted ${base.job.state}`);
+    const outcome = outcomeOf(job);
+    v.push(
+      `verdict: ${job.state}${job.error ? ` (${job.error.code}: ${job.error.reason})` : ""}${outcome ? ` outcome: ${outcome}` : ""}, unfaulted ${base.job.state}`,
+    );
   }
   if (opts.expectKill && cell.kills.length === 0) v.push("fired: the armed fault never fired");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.9.2",
+  "version": "4.10.0",
   "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/consent-broker.ts

@@ -30,6 +30,7 @@ import { CONSENT_PURPOSES, type ConsentPurpose } from "../integration-capabiliti
 import { CONSENT_SNAPSHOT_SCHEMA_VERSION } from "./version.js";
 import type { EventConsentSnapshot } from "./events.js";
 import type { EuUkVisitorPolicy } from "./plan.js";
+import { schedulePostPaint, type PostPaintWindow } from "./post-paint.js";
 
 /** The purpose that is always on and cannot be gated (charter floor). */
 const ESSENTIAL: ConsentPurpose = "essential";
@@ -479,8 +480,10 @@ export class ConsentBroker {
  * The tenant configuration supplies the analytics default and a stored viewer choice
  * overrides it. Global Privacy Control always denies analytics. Visitors the edge
  * classes as EU/EEA/UK/CH, or cannot class, get the tenant's EU/UK visitor policy:
- * `count-only` (default) keeps page views but stores nothing on the device, `none`
- * denies analytics, and `full` applies the default behavior. The same synchronous
+ * `ask` (default) counts page views without storing anything and prompts the visitor,
+ * and an Allow lifts the restriction for this context; `count-only` keeps page views
+ * but stores nothing on the device; `none` denies analytics; and `full` applies the
+ * default behavior. The same synchronous
  * early boot runs in both document mounts before any integration or measurement loader
  * can execute.
  */
@@ -515,6 +518,16 @@ export interface ViewerAnalyticsConsentState {
    * visitor-continuity storage reads this and falls back to a per-page memory id.
    */
   visitorStorage: "persistent" | "none";
+  /**
+   * Whether the EU/UK visitor policy currently restricts this visitor: no device
+   * storage, no marketing or personalization, and no tenant-local code.
+   */
+  regionRestricted: boolean;
+  /**
+   * `pending` when the `ask` policy applies and the visitor has not decided; the
+   * control then opens itself after paint. `none` otherwise.
+   */
+  prompt: "pending" | "none";
   tenantPublicId: string;
   environment: string;
   siteSurface: string;
@@ -616,18 +629,31 @@ export function applyEarlyViewerAnalyticsConsent(
 
   // The edge sets a class-only `tot_rgn` cookie on every HTML response
   // (visitor-region.mjs). An absent or unreadable class is unknown, and unknown gets
-  // the EU/UK policy until the region is known.
+  // the EU/UK policy until the region is known. Several `tot_rgn` cookies that disagree
+  // (one planted with another Domain or Path beside the edge's) are unknown too, so a
+  // planted class can never widen the edge's.
   let regionClass = "u";
   try {
-    const regionMatch = /(?:^|;\s*)tot_rgn=(eu|x|u)(?:;|$)/.exec(String(win.document?.cookie ?? ""));
-    if (regionMatch) regionClass = regionMatch[1] as string;
+    const regionClasses: string[] = [];
+    for (const part of String(win.document?.cookie ?? "").split(";")) {
+      const separator = part.indexOf("=");
+      if (separator !== -1 && part.slice(0, separator).trim() === "tot_rgn") regionClasses.push(part.slice(separator + 1).trim());
+    }
+    const firstClass = regionClasses[0];
+    if (
+      (firstClass === "eu" || firstClass === "x" || firstClass === "u") &&
+      regionClasses.every((candidate) => candidate === firstClass)
+    ) {
+      regionClass = firstClass;
+    }
   } catch {
     // An unreadable cookie jar leaves the region unknown.
   }
+  // An absent or unrecognized policy is `ask`: it never widens collection.
   const euUkVisitors: EuUkVisitorPolicy =
-    plan?.euUkVisitors === "full" || plan?.euUkVisitors === "none" ? plan.euUkVisitors : "count-only";
-  const regionRestricted = regionClass !== "x" && euUkVisitors !== "full";
-  const regionDeniesAnalytics = regionRestricted && euUkVisitors === "none";
+    plan?.euUkVisitors === "count-only" || plan?.euUkVisitors === "full" || plan?.euUkVisitors === "none"
+      ? plan.euUkVisitors
+      : "ask";
 
   let stored: { decision: ViewerAnalyticsConsentDecision; expiresAt: number } | null = null;
   // A stored record that is present but unreadable may have been a denial, so it denies
@@ -679,8 +705,19 @@ export function applyEarlyViewerAnalyticsConsent(
     }
   }
 
+  // Under `ask`, a visitor's own Allow for this exact context lifts the restriction.
+  const regionSensitive = regionClass !== "x";
+  const askUpgraded =
+    euUkVisitors === "ask" && stored?.decision === "granted" && !globalPrivacyControl && tenantApprovedAnalytics;
+  const regionRestricted = regionSensitive && euUkVisitors !== "full" && !askUpgraded;
+  const regionDeniesAnalytics = regionRestricted && euUkVisitors === "none";
+  // Until the visitor allows, `ask` counts page views exactly as `count-only` does; a
+  // Decline, a Close or no answer leaves it there.
+  const askRestricted = regionRestricted && euUkVisitors === "ask";
+
   const decision: ViewerAnalyticsConsentDecision =
-    globalPrivacyControl || !tenantApprovedAnalytics || regionDeniesAnalytics || (!stored && storedInvalid)
+    globalPrivacyControl || !tenantApprovedAnalytics || regionDeniesAnalytics || askRestricted ||
+      (!stored && storedInvalid)
       ? "denied"
       : stored?.decision ?? (tenantDefaultAnalytics ? "granted" : "denied");
   const source: ViewerAnalyticsConsentState["source"] = globalPrivacyControl
@@ -691,9 +728,12 @@ export function applyEarlyViewerAnalyticsConsent(
       ? "stored"
       : storedInvalid
         ? "stored-invalid"
-        : tenantDefaultAnalytics
-          ? "tenant-default"
-          : "default-deny";
+        : askRestricted
+          ? "eu-uk-policy"
+          : tenantDefaultAnalytics
+            ? "tenant-default"
+            : "default-deny";
+  const prompt = askRestricted && !stored && !globalPrivacyControl && tenantApprovedAnalytics ? "pending" : "none";
 
   // Under the EU/UK policy, marketing and personalization never run: neither can work
   // without storing an identifier on the device.
@@ -701,7 +741,9 @@ export function applyEarlyViewerAnalyticsConsent(
     (purpose) =>
       purpose === "essential" ||
       (purpose === "analytics"
-        ? decision === "granted" && tenantApprovedAnalytics
+        ? askRestricted
+          ? tenantDefaultAnalytics && !globalPrivacyControl
+          : decision === "granted" && tenantApprovedAnalytics
         : !regionRestricted && rawEligible.includes(purpose)),
   );
   const approved = canonicalPurposes.filter((purpose) => rawApproved.includes(purpose));
@@ -735,6 +777,8 @@ export function applyEarlyViewerAnalyticsConsent(
     region: regionClass === "eu" ? "eu-uk" : regionClass === "x" ? "other" : "unknown",
     euUkVisitors,
     visitorStorage,
+    regionRestricted,
+    prompt,
     tenantPublicId,
     environment,
     siteSurface,
@@ -820,22 +864,33 @@ export function setViewerAnalyticsConsent(
 
 function renderControlState(root: HTMLElement, state: ViewerAnalyticsConsentState): void {
   const status = root.querySelector<HTMLElement>("[data-tot-analytics-consent-status]");
+  const detail = root.querySelector<HTMLElement>("[data-tot-analytics-consent-detail]");
   const grant = root.querySelector<HTMLButtonElement>('[data-tot-analytics-consent-decision="granted"]');
   const deny = root.querySelector<HTMLButtonElement>('[data-tot-analytics-consent-decision="denied"]');
+  const countingOnly = state.regionRestricted && state.euUkVisitors === "ask" && state.canGrant;
   if (status) {
     status.textContent = state.source === "global-privacy-control"
       ? "Analytics off — Global Privacy Control"
       : state.decision === "granted"
         ? "Analytics on"
-        : "Analytics off";
+        : countingOnly
+          ? "Page counts only"
+          : "Analytics off";
+  }
+  if (detail) {
+    detail.textContent = countingOnly
+      ? "Page views are counted without storing anything on this device. Allow analytics to remember this device between visits."
+      : "Choose whether analytics may run on this site.";
   }
   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"));
+    // A visitor counted under `ask` has not declined until they say so.
+    const declined = state.decision === "denied" && (!countingOnly || state.source === "stored");
+    deny.disabled = declined;
+    deny.setAttribute("aria-pressed", String(declined));
   }
 }
 
@@ -844,7 +899,7 @@ function firstEnabledButton(root: HTMLElement): HTMLButtonElement | null {
 }
 
 /**
- * Bind each persistent "Analytics choices" disclosure to the control its
+ * Bind each tenant Privacy Policy "Analytics choices" disclosure to the control its
  * `aria-controls` names: a click opens the control and moves focus into it; a second
  * click, the control's Close button, or Escape inside it closes it again, and the
  * latter two return focus to the toggle.
@@ -882,6 +937,38 @@ function bindViewerAnalyticsChoicesToggles(win: ViewerConsentWindow): void {
   });
 }
 
+/** Show or hide a control and keep every disclosure that names it in step. */
+function setControlVisible(win: ViewerConsentWindow, root: HTMLElement, visible: boolean): void {
+  root.hidden = !visible;
+  if (!root.id) return;
+  win.document?.querySelectorAll<HTMLElement>("[data-tot-analytics-choices-toggle]").forEach((toggle) => {
+    if (toggle.getAttribute("aria-controls") === root.id) toggle.setAttribute("aria-expanded", String(visible));
+  });
+}
+
+/**
+ * Open each control for a visitor the `ask` policy has not heard from. It runs after
+ * paint and idle so it never delays the page, and the control is a fixed overlay so it
+ * shifts no layout. Focus stays where the visitor left it.
+ */
+function scheduleViewerAnalyticsPrompt(
+  win: ViewerConsentWindow,
+  roots: NodeListOf<HTMLElement> | undefined,
+  state: ViewerAnalyticsConsentState,
+): void {
+  if (state.prompt !== "pending" || !roots || roots.length === 0) return;
+  if (typeof win["setTimeout"] !== "function" || typeof win.addEventListener !== "function") return;
+  schedulePostPaint(win as unknown as PostPaintWindow, () => {
+    const latest = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined;
+    if (latest?.prompt !== "pending") return;
+    roots.forEach((root) => {
+      renderControlState(root, latest);
+      root.dataset["totAnalyticsConsentPrompted"] = "true";
+      setControlVisible(win, root, true);
+    });
+  });
+}
+
 /** Bind the renderer-owned control once; safe when a document contains no analytics plan. */
 export function bootViewerAnalyticsConsentControl(
   win: ViewerConsentWindow,
@@ -897,15 +984,28 @@ export function bootViewerAnalyticsConsentControl(
     root.addEventListener("click", (event) => {
       const target = event.target;
       if (!(target instanceof Element)) return;
+      // Close records nothing, so an unanswered prompt returns on the next page.
+      if (target.closest("[data-tot-analytics-consent-close]")) {
+        delete root.dataset["totAnalyticsConsentPrompted"];
+        setControlVisible(win, root, false);
+        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()));
+      // An answered prompt goes away; the disclosure reopens the control on demand.
+      if (root.dataset["totAnalyticsConsentPrompted"] === "true") {
+        delete root.dataset["totAnalyticsConsentPrompted"];
+        setControlVisible(win, root, false);
+        return;
+      }
       // The pressed button is now disabled; keep keyboard focus inside the control.
       if (button?.disabled) firstEnabledButton(root)?.focus();
     });
   });
   bindViewerAnalyticsChoicesToggles(win);
+  scheduleViewerAnalyticsPrompt(win, roots, current);
 
   const storageBoundGlobal = "__TOT_VIEWER_ANALYTICS_CONSENT_STORAGE_BOUND__";
   if (win.addEventListener && win[storageBoundGlobal] !== true) {

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

@@ -57,8 +57,9 @@ import { INTEGRATION_ENVIRONMENTS, INTEGRATION_SITE_SURFACES } from "./environme
 import type { IntegrationEnvironment, IntegrationSiteSurface } from "./environment.js";
 import { findForbiddenFields } from "./secrets.js";
 import {
+  MANAGED_ANALYTICS_CAMPAIGN_FIELDS,
   resemblesManagedAnalyticsPii,
-  resemblesManagedAnalyticsProtectedValue,
+  screenManagedAnalyticsCampaign,
 } from "./managed-analytics-value-safety.js";
 
 /**
@@ -349,8 +350,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}$/;
 function validatePageAttribution(parent: Record<string, unknown>, v: Violations): void {
   const attribution = childObject(parent, "attribution", v, "data");
   if (!attribution) return;
@@ -389,27 +388,24 @@ function validatePageAttribution(parent: Record<string, unknown>, v: Violations)
   if ("utm" in attribution) {
     const utm = childObject(attribution, "utm", v, "data.attribution");
     if (utm) {
-      rejectUnknownKeys(utm, UTM_FIELDS, v, "data.attribution.utm");
+      rejectUnknownKeys(utm, MANAGED_ANALYTICS_CAMPAIGN_FIELDS, v, "data.attribution.utm");
       if (Object.keys(utm).length === 0) {
         v.add("data.attribution.utm", "empty", "UTM must contain at least one allowlisted field.");
       }
-      for (const key of UTM_FIELDS) {
+      const strings: Record<string, string> = {};
+      for (const key of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
         if (!(key in utm)) continue;
         const value = reqString(utm, key, v, "data.attribution.utm");
-        if (value !== undefined && !SAFE_UTM_VALUE.test(value)) {
-          v.add(
-            `data.attribution.utm.${key}`,
-            "format",
-            `UTM ${key} must be a 1-128 character opaque campaign token.`,
-          );
-        }
-        if (value !== undefined && resemblesManagedAnalyticsProtectedValue(value)) {
-          v.add(
-            `data.attribution.utm.${key}`,
-            "protected_value",
-            `UTM ${key} resembles PII or protected material and must not be emitted.`,
-          );
-        }
+        if (value !== undefined) strings[key] = value;
+      }
+      for (const { field, reason } of screenManagedAnalyticsCampaign(strings).rejected) {
+        v.add(
+          `data.attribution.utm.${field}`,
+          reason,
+          reason === "format"
+            ? `UTM ${field} must be a 1-128 character opaque campaign token.`
+            : `UTM ${field} resembles PII or protected material and must not be emitted.`,
+        );
       }
     }
   }

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

@@ -56,6 +56,7 @@ export * from "./manifest.js";
 export * from "./plan.js";
 export * from "./resolve.js";
 export * from "./platform-adapters.js";
+export * from "./tenant-analytics.js";
 export * from "./native-amplitude.js";
 export * from "./native-ga4.js";
 export * from "./native-ga4-sandbox.js";

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

@@ -59,8 +59,8 @@ import {
 import { schedulePostPaint, type PostPaintWindow } from "./post-paint.js";
 import { scheduleGa4Sandbox, type Ga4SandboxScheduleWindow } from "./ga4-sandbox-schedule.js";
 import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
-import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
-import { managedAnalyticsOpaqueRevision } from "./managed-analytics-value-safety.js";
+import { minimizePageAttribution, readGoogleAdsClickIds, type ManagedPageViewInput } from "./managed-analytics.js";
+import { managedAnalyticsOpaqueRevision, type GoogleAdsClickIds } from "./managed-analytics-value-safety.js";
 import {
   CONTACT_SALES_ACTION_REGISTRY,
   createContactSalesActionSource,
@@ -349,13 +349,13 @@ function defaultConsentGate(
 }
 
 /**
- * Whether the tenant's EU/UK visitor policy governs this document: the edge classed the
- * visitor as EU/EEA/UK/CH or could not class them, and the tenant has not taken `full`
- * responsibility. A missing state global applies it (fail closed).
+ * Whether the tenant's EU/UK visitor policy governs this document, as the early consent
+ * boot decided it (`regionRestricted`). Only an explicit `false` lifts it: a missing
+ * state global or a missing or non-boolean flag applies it (fail closed).
  */
 function euUkPolicyApplies(win: LifecycleWindow): boolean {
-  const state = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined;
-  return !state || (state.region !== "other" && state.euUkVisitors !== "full");
+  const state = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as Partial<ViewerAnalyticsConsentState> | undefined;
+  return state?.regionRestricted !== false;
 }
 
 /**
@@ -367,6 +367,39 @@ function persistentVisitorStorage(win: LifecycleWindow): boolean {
   return state?.visitorStorage === "persistent";
 }
 
+/**
+ * Whether landing click identifiers may reach GA4: the visitor is known to be outside
+ * the EU/UK and analytics may keep them on this device. GPC, a saved denial, `count-only`,
+ * an unknown region, and an EU/UK visitor under any tenant policy all forward nothing.
+ * A missing state global allows nothing (fail closed).
+ */
+function landingClickIdsAllowed(win: LifecycleWindow): boolean {
+  const state = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined;
+  return state?.visitorStorage === "persistent" && state.region === "other";
+}
+
+/** Windows whose landing click identifiers already went out; a back-forward restore never resends them. */
+const landingClickIdsTaken = new WeakSet<object>();
+
+/**
+ * The GA4 host capability over this document's landing URL: identifiers are read once,
+ * when the lifecycle is built, and released once, to the page view of the landing path,
+ * only while {@link landingClickIdsAllowed} holds at that moment.
+ */
+function landingClickIdSource(
+  win: LifecycleWindow,
+  tenantPublicId: string,
+): ((path: string) => GoogleAdsClickIds | undefined) | undefined {
+  const clickIds = readGoogleAdsClickIds(win.location.href);
+  if (!clickIds) return undefined;
+  const landingPath = canonicalDocumentPath(win.location.pathname, tenantPublicId);
+  return (path) => {
+    if (path !== landingPath || landingClickIdsTaken.has(win) || !landingClickIdsAllowed(win)) return undefined;
+    landingClickIdsTaken.add(win);
+    return clickIds;
+  };
+}
+
 /**
  * Under the EU/UK policy only a reviewed platform adapter may run: its
  * visitor storage goes through this host's continuity seam, which then keeps nothing on
@@ -500,6 +533,7 @@ function createDocumentLifecycle(
           ? win["localStorage"] as VisitorContinuityStorage | undefined
           : undefined),
     }),
+    takeLandingClickIds: landingClickIdSource(win, descriptor.tenantPublicId),
     nativeGa4Transport: () => {
       if (options.nativeGa4Transport) return options.nativeGa4Transport;
       if (typeof document === "undefined" || typeof MessageChannel === "undefined") {

package/packages/public-runtime/src/integration/managed-analytics-value-safety.ts

@@ -1,12 +1,95 @@
 /** Shared PII-value canary for managed browser events and their diagnostics. */
-import { MANAGED_ANALYTICS_PII_VALUE_PATTERN } from "./managed-analytics-api-v1-safety.mjs";
+import {
+  MANAGED_ANALYTICS_PII_VALUE_PATTERN,
+  MANAGED_ANALYTICS_SECRET_VALUE_PATTERN,
+} from "./managed-analytics-api-v1-safety.mjs";
 import { fnv1a128Hex } from "./digest.js";
 
 const MANAGED_ANALYTICS_PII_VALUE = new RegExp(MANAGED_ANALYTICS_PII_VALUE_PATTERN);
+const MANAGED_ANALYTICS_SECRET_VALUE = new RegExp(MANAGED_ANALYTICS_SECRET_VALUE_PATTERN);
 const MANAGED_ANALYTICS_PROTECTED_VALUE =
   /(?:@|\d{7,}|(?:^|[./_~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[./_~-]))/i;
 const OPAQUE_HEX_ALPHABET = "abcdefghijklmnop";
 
+/** The five standard UTM fields, without their `utm_` prefix. */
+export const MANAGED_ANALYTICS_CAMPAIGN_FIELDS = ["source", "medium", "campaign", "term", "content"] as const;
+export type ManagedAnalyticsCampaignField = (typeof MANAGED_ANALYTICS_CAMPAIGN_FIELDS)[number];
+export type ManagedAnalyticsCampaign = Partial<Record<ManagedAnalyticsCampaignField, string>>;
+
+/** A dropped campaign field. It names the field and the reason, never the value. */
+export interface ManagedAnalyticsCampaignRejection {
+  field: ManagedAnalyticsCampaignField;
+  reason: "format" | "protected_value";
+}
+
+export interface ManagedAnalyticsCampaignScreen {
+  kept: ManagedAnalyticsCampaign;
+  rejected: ManagedAnalyticsCampaignRejection[];
+}
+
+const CAMPAIGN_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+/** Credential words as a whole token segment. `token` and `preview` are ordinary campaign words. */
+const CAMPAIGN_CREDENTIAL_WORD = /(?:^|[._~-])(?:bearer|password|secret|authorization|credential)(?:$|[._~-])/i;
+/** A labelled token may carry a 7-8 digit stamp (`_20261027`); a longer run could be a dialable number. */
+const CAMPAIGN_LONG_DIGIT_RUN = /\d{9,}/;
+/**
+ * A bare number is never a campaign token. A Google Ads ValueTrack `{campaignid}` has the
+ * same shape as an international phone number written without `+`, and neither `utm_source`
+ * nor length separates them, so it is rejected; GA4 still attributes Ads traffic by click id.
+ */
+const CAMPAIGN_BARE_DIGITS = /^\d{7,}$/;
+
+function campaignTokenRejection(value: unknown): ManagedAnalyticsCampaignRejection["reason"] | undefined {
+  if (typeof value !== "string" || !CAMPAIGN_TOKEN.test(value)) return "format";
+  if (
+    resemblesManagedAnalyticsPii(value) || MANAGED_ANALYTICS_SECRET_VALUE.test(value) ||
+    CAMPAIGN_CREDENTIAL_WORD.test(value)
+  ) return "protected_value";
+  return CAMPAIGN_BARE_DIGITS.test(value) || CAMPAIGN_LONG_DIGIT_RUN.test(value) ? "protected_value" : undefined;
+}
+
+/**
+ * The one campaign-token policy for every layer that carries UTM values: minimization,
+ * event validation, the GA4 parent and sandbox, and Amplitude. Each present field is kept
+ * or rejected on its own, so one unsafe value never costs the page view its other fields.
+ */
+export function screenManagedAnalyticsCampaign(utm: Readonly<Record<string, unknown>>): ManagedAnalyticsCampaignScreen {
+  const kept: ManagedAnalyticsCampaign = {};
+  const rejected: ManagedAnalyticsCampaignRejection[] = [];
+  for (const field of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
+    if (!Object.hasOwn(utm, field)) continue;
+    const value = utm[field];
+    const reason = campaignTokenRejection(value);
+    if (reason) rejected.push({ field, reason });
+    else kept[field] = value as string;
+  }
+  return { kept, rejected };
+}
+
+/** The Google Ads click identifiers a landing URL may carry to GA4. */
+export const GOOGLE_ADS_CLICK_ID_KEYS = ["gclid", "gbraid", "wbraid"] as const;
+export type GoogleAdsClickIdKey = (typeof GOOGLE_ADS_CLICK_ID_KEYS)[number];
+export type GoogleAdsClickIds = Partial<Record<GoogleAdsClickIdKey, string>>;
+
+/** Auto-tagging writes URL-safe base64; the length bound only caps hostile input. */
+const GOOGLE_ADS_CLICK_ID = /^[A-Za-z0-9_-]{1,512}$/;
+
+/** A click identifier safe to place on a GA4 `page_location`: URL-safe, bounded, and not PII- or secret-shaped. */
+export function isGoogleAdsClickIdValue(value: unknown): value is string {
+  return typeof value === "string" && GOOGLE_ADS_CLICK_ID.test(value) &&
+    !resemblesManagedAnalyticsPii(value) && !MANAGED_ANALYTICS_SECRET_VALUE.test(value);
+}
+
+/** A non-empty record of known click-identifier keys, every value valid. */
+export function isGoogleAdsClickIds(value: unknown): value is GoogleAdsClickIds {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  const entries = Object.entries(value);
+  return entries.length > 0 && entries.every(([key, id]) =>
+    (GOOGLE_ADS_CLICK_ID_KEYS as readonly string[]).includes(key) && isGoogleAdsClickIdValue(id));
+}
+
 /** True when a public string resembles an email, SSN, payment card, or phone number. */
 export function resemblesManagedAnalyticsPii(value: unknown): boolean {
   return typeof value === "string" && MANAGED_ANALYTICS_PII_VALUE.test(value);