@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

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

@@ -0,0 +1,352 @@
+/**
+ * Storefront-owned GA4 browser adapter.
+ *
+ * The adapter consumes only the manually-authored page/action events exposed by the
+ * scoped lifecycle subscription. It does not load vendor code, inspect the document,
+ * or persist browser identity. A reviewed direct POST sends a closed, anonymous
+ * payload to one exact collection origin after the shared broker has applied consent
+ * and logical-event dedupe.
+ */
+import type { IntegrationLifecycleContext, IntegrationLifecycleModule, LifecycleUpdateReason } from "./lifecycle.js";
+import type { CommerceEvent, CommerceEventType } from "./events.js";
+import { APPROVED_MARKETING_ACTION_NAMES, validateCommerceEvent } from "./events.js";
+import { isPurposeEligible, parseConsentSnapshot } from "./consent-broker.js";
+import { destinationIdConfigKey, GOOGLE_MEASUREMENT_ADAPTER } from "./platform-adapters.js";
+import { INTEGRATION_ENVIRONMENTS, type IntegrationEnvironment } from "./environment.js";
+import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+
+export const GA4_COLLECTION_ORIGIN = "https://www.google-analytics.com" as const;
+export const GA4_COLLECTION_ENDPOINT = `${GA4_COLLECTION_ORIGIN}/g/collect` as const;
+export const NATIVE_GA4_ENTRY_URL = "/platform/google-measurement/v1/entry.mjs" as const;
+export const NATIVE_GA4_ADAPTER_VERSION = "1.0.0" as const;
+export const NATIVE_GA4_RUNTIME_ID = "native-ga4-v1" as const;
+
+export const NATIVE_GA4_EVENT_TYPES = Object.freeze([
+  "storefront.page.viewed.v1",
+  "storefront.page.viewed.v2",
+  "storefront.action.activated.v1",
+] as const satisfies readonly CommerceEventType[]);
+
+const NATIVE_GA4_EVENT_SET: ReadonlySet<string> = new Set(NATIVE_GA4_EVENT_TYPES);
+const APPROVED_ACTION_SET: ReadonlySet<string> = new Set(APPROVED_MARKETING_ACTION_NAMES);
+const CONFIG_KEYS: ReadonlySet<string> = new Set(
+  INTEGRATION_ENVIRONMENTS.map(destinationIdConfigKey),
+);
+
+export type NativeGa4DiagnosticCode =
+  | "configuration_invalid"
+  | "consent_ineligible"
+  | "event_rejected"
+  | "duplicate_suppressed"
+  | "teardown_failed"
+  | "transport_failed";
+
+export interface NativeGa4Observation {
+  code: NativeGa4DiagnosticCode;
+}
+
+export interface NativeGa4CollectRequest {
+  endpoint: typeof GA4_COLLECTION_ENDPOINT;
+  /** Closed GA4 request body. Values are anonymous strings, never raw event envelopes. */
+  fields: Readonly<Record<string, string>>;
+}
+
+export type NativeGa4Transport = (
+  request: NativeGa4CollectRequest,
+) => void | Promise<void>;
+
+export type NativeGa4Observer = (observation: NativeGa4Observation) => void;
+
+export interface NativeGa4ModuleOptions {
+  transport: NativeGa4Transport;
+  observe?: NativeGa4Observer;
+}
+
+interface ActiveGa4Config {
+  destinationId: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationLifecycleContext["environment"]["siteSurface"];
+}
+
+function observeSafely(observer: NativeGa4Observer | undefined, code: NativeGa4DiagnosticCode): void {
+  try {
+    observer?.(Object.freeze({ code }));
+  } catch {
+    // Diagnostics are fail-soft and carry no exception text or payload.
+  }
+}
+
+function configuredFor(ctx: IntegrationLifecycleContext): ActiveGa4Config | null {
+  if (ctx.appId !== GOOGLE_MEASUREMENT_ADAPTER.adapterId) return null;
+  if (!hasAnalyticsConsent(ctx)) return null;
+
+  for (const key of Object.keys(ctx.config)) {
+    if (!CONFIG_KEYS.has(key)) return null;
+  }
+
+  const liveId = ctx.config[destinationIdConfigKey("live")];
+  if (typeof liveId !== "string" || !GOOGLE_MEASUREMENT_ADAPTER.validateId(liveId)) return null;
+  for (const environment of INTEGRATION_ENVIRONMENTS) {
+    const value = ctx.config[destinationIdConfigKey(environment)];
+    if (value === undefined) continue;
+    if (typeof value !== "string" || !GOOGLE_MEASUREMENT_ADAPTER.validateId(value)) return null;
+    if (environment !== "live" && value === liveId) return null;
+  }
+
+  const destinationId = ctx.config[destinationIdConfigKey(ctx.environment.environment)];
+  if (
+    typeof destinationId !== "string" ||
+    !GOOGLE_MEASUREMENT_ADAPTER.validateId(destinationId)
+  ) {
+    return null;
+  }
+  return {
+    destinationId,
+    environment: ctx.environment.environment,
+    siteSurface: ctx.environment.siteSurface,
+  };
+}
+
+function hasAnalyticsConsent(ctx: IntegrationLifecycleContext): boolean {
+  const consent = parseConsentSnapshot(ctx.consent);
+  return consent !== null && isPurposeEligible(consent, "analytics");
+}
+
+function fnv1a32(value: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    hash = Math.imul(hash ^ (code & 0xff), 0x01000193);
+    hash = Math.imul(hash ^ ((code >> 8) & 0xff), 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+/** GA4 requires a client id. Derive an opaque document/session value without storage. */
+function anonymousClientId(event: CommerceEvent): string {
+  const high = fnv1a32(`ga4:${event.correlation.id}`);
+  const low = fnv1a32(`ga4:${event.correlation.expiresAt}`);
+  return `ga4.${high.toString(16)}.${low.toString(16)}`;
+}
+
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  const actual = Object.keys(value);
+  return actual.length <= allowed.length && actual.every((key) => allowed.includes(key));
+}
+
+function mapEvent(config: ActiveGa4Config, input: unknown): NativeGa4CollectRequest | null {
+  const validated = validateCommerceEvent(input);
+  if (!validated.ok) return null;
+  const event = validated.value;
+  if (!NATIVE_GA4_EVENT_SET.has(event.type)) return null;
+  if (event.storefront.emitter !== "browser") return null;
+  if (event.storefront.environment !== config.environment) return null;
+  if (event.storefront.siteSurface !== config.siteSurface) return null;
+  if (!event.consent.eligiblePurposes.includes("analytics")) return null;
+
+  const fields: Record<string, string> = {
+    v: "2",
+    tid: config.destinationId,
+    cid: anonymousClientId(event),
+  };
+
+  if (event.type === "storefront.page.viewed.v1") {
+    if (!exactKeys(event.data, ["path"]) || typeof event.data["path"] !== "string") return null;
+    fields["en"] = "page_view";
+    fields["ep.page_path"] = event.data["path"];
+  } else if (event.type === "storefront.page.viewed.v2") {
+    if (!exactKeys(event.data, ["path", "attribution"]) || typeof event.data["path"] !== "string") return null;
+    fields["en"] = "page_view";
+    fields["ep.page_path"] = event.data["path"];
+    const attribution = event.data["attribution"];
+    if (typeof attribution === "object" && attribution !== null && !Array.isArray(attribution)) {
+      const record = attribution as Record<string, unknown>;
+      const referrer = record["referrer"];
+      if (typeof referrer === "object" && referrer !== null && !Array.isArray(referrer)) {
+        const origin = (referrer as Record<string, unknown>)["origin"];
+        if (typeof origin === "string") fields["ep.referrer_origin"] = origin;
+      }
+      const utm = record["utm"];
+      if (typeof utm === "object" && utm !== null && !Array.isArray(utm)) {
+        for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
+          const value = (utm as Record<string, unknown>)[key];
+          if (typeof value === "string") fields[`ep.utm_${key}`] = value;
+        }
+      }
+    }
+  } else {
+    if (!exactKeys(event.data, ["name"])) return null;
+    const name = event.data["name"];
+    if (typeof name !== "string" || !APPROVED_ACTION_SET.has(name)) return null;
+    fields["en"] = name;
+  }
+
+  return Object.freeze({ endpoint: GA4_COLLECTION_ENDPOINT, fields: Object.freeze(fields) });
+}
+
+/**
+ * Build the lifecycle entry module used by the platform-owned GA4 asset. The host
+ * supplies fetch as a capability; this module never reaches through a browser global.
+ */
+export function createNativeGa4Module(options: NativeGa4ModuleOptions): IntegrationLifecycleModule {
+  let unsubscribe: (() => void) | null = null;
+  let active: ActiveGa4Config | null = null;
+  let disposed = false;
+  const delivered = new Set<string>();
+  const deliveredOrder: string[] = [];
+
+  const stop = (): boolean => {
+    const release = unsubscribe;
+    active = null;
+    if (!release) return true;
+    try {
+      release();
+      unsubscribe = null;
+      return true;
+    } catch {
+      observeSafely(options.observe, "teardown_failed");
+      return false;
+    }
+  };
+
+  const apply = (ctx: IntegrationLifecycleContext): void => {
+    if (!stop()) return;
+    if (disposed) return;
+    const next = configuredFor(ctx);
+    if (!next) {
+      observeSafely(
+        options.observe,
+        hasAnalyticsConsent(ctx) ? "configuration_invalid" : "consent_ineligible",
+      );
+      return;
+    }
+    if (!ctx.subscribe) {
+      observeSafely(options.observe, "configuration_invalid");
+      return;
+    }
+    active = next;
+    unsubscribe = ctx.subscribe({
+      types: NATIVE_GA4_EVENT_TYPES,
+      consentPurpose: "analytics",
+      sink: {
+        kind: "callback",
+        handler(event) {
+          const current = active;
+          if (disposed || !current) return;
+          if (delivered.has(event.id)) {
+            observeSafely(options.observe, "duplicate_suppressed");
+            return;
+          }
+          const request = mapEvent(current, event);
+          if (!request) {
+            observeSafely(options.observe, "event_rejected");
+            return;
+          }
+          delivered.add(event.id);
+          deliveredOrder.push(event.id);
+          if (deliveredOrder.length > 1_024) {
+            const oldest = deliveredOrder.shift();
+            if (oldest !== undefined) delivered.delete(oldest);
+          }
+          try {
+            const result = options.transport(request);
+            if (result && typeof result.then === "function") {
+              void result.catch(() => observeSafely(options.observe, "transport_failed"));
+            }
+          } catch {
+            observeSafely(options.observe, "transport_failed");
+          }
+        },
+      },
+    });
+  };
+
+  return {
+    init(ctx) {
+      apply(ctx);
+    },
+    update(_reason: LifecycleUpdateReason, ctx) {
+      apply(ctx);
+    },
+    dispose() {
+      disposed = true;
+      stop();
+    },
+  };
+}
+
+/** A fixed-origin, credentialless browser transport for the native lifecycle entry. */
+export function createNativeGa4FetchTransport(
+  fetchCapability: typeof fetch,
+): NativeGa4Transport {
+  return async (request) => {
+    if (request.endpoint !== GA4_COLLECTION_ENDPOINT) throw new Error("ga4_transport_invalid");
+    if (!safeTransportFields(request.fields)) throw new Error("ga4_transport_invalid");
+    const response = await fetchCapability(request.endpoint, {
+      method: "POST",
+      body: new URLSearchParams(request.fields).toString(),
+      mode: "no-cors",
+      credentials: "omit",
+      referrerPolicy: "no-referrer",
+      keepalive: true,
+      headers: { "content-type": "text/plain;charset=UTF-8" },
+    });
+    // Opaque no-cors responses are expected. A non-opaque explicit failure is stable.
+    if (response.type !== "opaque" && !response.ok) throw new Error("ga4_transport_failed");
+  };
+}
+
+const GA4_OPTIONAL_PAGE_FIELDS = [
+  "ep.referrer_origin",
+  "ep.utm_source",
+  "ep.utm_medium",
+  "ep.utm_campaign",
+  "ep.utm_term",
+  "ep.utm_content",
+] as const;
+const SAFE_CAMPAIGN_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+
+function safeTransportFields(fields: Readonly<Record<string, string>>): boolean {
+  const keys = Object.keys(fields);
+  const allowed = new Set(["v", "tid", "cid", "en", "ep.page_path", ...GA4_OPTIONAL_PAGE_FIELDS]);
+  if (keys.some((key) => !allowed.has(key))) return false;
+  if (fields["v"] !== "2") return false;
+  if (!GOOGLE_MEASUREMENT_ADAPTER.validateId(fields["tid"] ?? "")) return false;
+  if (!/^ga4\.[a-f0-9]{1,8}\.[a-f0-9]{1,8}$/.test(fields["cid"] ?? "")) return false;
+  if (Object.values(fields).some((value) => resemblesManagedAnalyticsPii(value))) return false;
+
+  const eventName = fields["en"];
+  if (eventName !== "page_view") {
+    return (
+      eventName !== undefined &&
+      APPROVED_ACTION_SET.has(eventName) &&
+      keys.length === 4 &&
+      keys.every((key) => ["v", "tid", "cid", "en"].includes(key))
+    );
+  }
+
+  const path = fields["ep.page_path"];
+  if (
+    typeof path !== "string" ||
+    !path.startsWith("/") ||
+    path.startsWith("//") ||
+    path.includes("\\") ||
+    path.includes("?") ||
+    path.includes("#")
+  ) return false;
+  const origin = fields["ep.referrer_origin"];
+  if (origin !== undefined) {
+    try {
+      const parsed = new URL(origin);
+      if (!["http:", "https:"].includes(parsed.protocol) || parsed.origin !== origin) return false;
+    } catch {
+      return false;
+    }
+  }
+  for (const key of GA4_OPTIONAL_PAGE_FIELDS) {
+    if (key === "ep.referrer_origin") continue;
+    const value = fields[key];
+    if (value !== undefined && !SAFE_CAMPAIGN_VALUE.test(value)) return false;
+  }
+  return true;
+}