@tokenoftrust/storefront-runner 2.2.16 → 2.2.18

package/apps/storefront/integrations/lifecycle-host-asset.mjs

@@ -21,7 +21,8 @@
  * passes — the client pass included — runs with `build.ssr === true`, so a Vite plugin
  * cannot tell them apart, while `config.build.client` says it outright.
  */
-import { mkdir, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,6 +30,7 @@ import {
   LIFECYCLE_HOST_ASSET_PATH,
   LIFECYCLE_HOST_COMPATIBILITY_ASSET_PATHS,
 } from "@tot/public-runtime/integration/lifecycle-host-asset";
+import { decideLifecycleHostLock, formatLifecycleHostLockReport } from "../../../scripts/lib/lifecycle-host-lock.mjs";
 
 const HOST_ASSET_PATHS = Object.freeze([
   ...LIFECYCLE_HOST_COMPATIBILITY_ASSET_PATHS,
@@ -42,6 +44,11 @@ const HOST_ENTRY = fileURLToPath(
   ),
 );
 
+const LOCK_URL = new URL(
+  "../../../packages/public-runtime/src/integration/lifecycle-host-asset.lock.json",
+  import.meta.url,
+);
+
 /**
  * Bundle the host to a single self-contained ES module.
  *
@@ -124,6 +131,30 @@ export function lifecycleHostAsset() {
         if (!clientDir) throw new Error("the lifecycle host has no resolved client output dir");
         const outputDir = clientDir;
         const code = await bundleLifecycleHost();
+        const hash = createHash("sha256").update(code, "utf8").digest("hex");
+
+        // Every HOST_ASSET_PATH is served under an `immutable, max-age=1yr` Cache-Control
+        // (scripts/publish/lib/s3-publish.mjs PLATFORM_ASSET_PREFIX) — once published, a
+        // path's bytes may never change, or visitors who already cached it are stuck on
+        // stale tracking/consent behavior for up to a year with nothing to notice it. This
+        // is the guard for that: refuse the build rather than silently rewrite a path that
+        // already shipped different bytes.
+        const lock = JSON.parse(await readFile(LOCK_URL, "utf8"));
+        const decision = decideLifecycleHostLock(
+          lock,
+          HOST_ASSET_PATHS.map((assetPath) => ({ assetPath, hash })),
+        );
+        if (!decision.ok) {
+          throw new Error(formatLifecycleHostLockReport(decision));
+        }
+        if (JSON.stringify(decision.nextLock) !== JSON.stringify(lock)) {
+          await writeFile(LOCK_URL, `${JSON.stringify(decision.nextLock, null, 2)}\n`, "utf8");
+          logger.warn(
+            "lifecycle host lock recorded a new path — commit " +
+              "packages/public-runtime/src/integration/lifecycle-host-asset.lock.json",
+          );
+        }
+
         await Promise.all(HOST_ASSET_PATHS.map(async (assetPath) => {
           const target = fileURLToPath(new URL(assetPath, outputDir));
           await mkdir(dirname(target), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.16",
+  "version": "2.2.18",
   "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/lifecycle-host-asset.lock.json

@@ -0,0 +1,4 @@
+{
+  "platform/lifecycle/v2/boot.mjs": "ed2c69b80fb2e1472d0b19631efec5ccb26a395a5f4820a54f55435deca6eb46",
+  "platform/lifecycle/v3/boot.mjs": "ed2c69b80fb2e1472d0b19631efec5ccb26a395a5f4820a54f55435deca6eb46"
+}

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

@@ -6,6 +6,15 @@
  * payload to one exact collection endpoint. The fixed device value groups events
  * as non-identifying storefront traffic; it is never derived from a browser,
  * person, account, persisted client value, network address, or device signal.
+ *
+ * Channel ATTRIBUTION (UTM tokens + the referrer's origin) is allowed through as
+ * plain `event_properties`: it is a minimized, campaign-scoped label already
+ * validated upstream (`events.ts` `validatePageAttribution`), not a visitor or
+ * device signal, and this adapter re-screens each value for PII before sending
+ * it regardless. A persistent/session identity is a different thing entirely —
+ * it stays out, on purpose: `device_id` remains the fixed, non-identifying value
+ * below and there is still no `session_id`, `user_id`, or any persisted client
+ * value anywhere in this file.
  */
 import type { CommerceEventBroker, CommerceEventSubscription } from "./commerce-broker.js";
 import {
@@ -47,13 +56,23 @@ export const AMPLITUDE_HTTP_EVENT_TYPES = Object.freeze([
   "storefront.action.activated.v1",
 ] as const);
 
+/** The flat channel-attribution keys this adapter will forward, mirroring `events.ts` UTM_FIELDS. */
+export type AmplitudeAttributionProperties = Partial<{
+  utm_source: string;
+  utm_medium: string;
+  utm_campaign: string;
+  utm_term: string;
+  utm_content: string;
+  referrer_origin: string;
+}>;
+
 export interface AmplitudeHttpEvent {
   event_type: "page_view" | (typeof APPROVED_MARKETING_ACTION_NAMES)[number];
   device_id: typeof ANONYMOUS_DEVICE_ID;
   insert_id: string;
   /** Occurrence time, epoch milliseconds. */
   time: number;
-  event_properties: GovernedEventProperties & { page_path?: string };
+  event_properties: GovernedEventProperties & { page_path?: string } & AmplitudeAttributionProperties;
 }
 
 export const AMPLITUDE_DEDUPE_CAPACITY = 512 as const;
@@ -104,6 +123,44 @@ class BoundedInsertIds {
   }
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Flatten the already-validated `data.attribution` object (`events.ts`
+ * `validatePageAttribution` — a minimized referrer origin plus up to five UTM
+ * tokens) into Amplitude's flat `event_properties`. Re-screened for PII here
+ * rather than trusted from upstream validation alone, matching `isSafePagePath`'s
+ * own double-check: a field that resembles PII is dropped individually rather
+ * than failing the whole page-view event.
+ */
+function extractAttributionProperties(data: Record<string, unknown>): AmplitudeAttributionProperties {
+  const attribution = data["attribution"];
+  if (!isPlainObject(attribution)) return {};
+  const out: AmplitudeAttributionProperties = {};
+
+  const utm = attribution["utm"];
+  if (isPlainObject(utm)) {
+    for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
+      const value = utm[key];
+      if (typeof value === "string" && value.length > 0 && !resemblesManagedAnalyticsPii(value)) {
+        out[`utm_${key}`] = value;
+      }
+    }
+  }
+
+  const referrer = attribution["referrer"];
+  if (isPlainObject(referrer)) {
+    const origin = referrer["origin"];
+    if (typeof origin === "string" && origin.length > 0 && !resemblesManagedAnalyticsPii(origin)) {
+      out.referrer_origin = origin;
+    }
+  }
+
+  return out;
+}
+
 function isSafePagePath(value: unknown): value is string {
   return typeof value === "string" && value.startsWith("/") && !value.startsWith("//") &&
     !value.includes("\\") && !value.includes("?") && !value.includes("#") &&
@@ -166,7 +223,12 @@ export function mapCommerceEventToAmplitude(
   }
   const path = event.data["path"];
   if (!isSafePagePath(path)) return null;
-  return { ...base, event_type: "page_view", event_properties: { ...governed, page_path: path } };
+  const attribution = extractAttributionProperties(event.data);
+  return {
+    ...base,
+    event_type: "page_view",
+    event_properties: { ...governed, page_path: path, ...attribution },
+  };
 }
 
 export interface RegisterAmplitudeHttpDestinationInput {