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

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

@@ -0,0 +1,383 @@
+/**
+ * The document-scoped bridge from platform-owned semantic action boundaries to the
+ * versioned commerce-event broker.
+ *
+ * This bridge deliberately has no DOM input. Its action boundary does not accept
+ * selectors, elements, labels, text, classes, forms, destinations, analytics commands,
+ * or arbitrary event data. Platform components call {@link activate} (or publish
+ * through the injected typed source) with one approved semantic name and an opaque
+ * logical identity. The existing {@link CommerceEventBroker} remains the only authority
+ * that stamps trusted context, validates the closed event contract, applies consent,
+ * deduplicates, and isolates subscriber failures.
+ */
+import type { CommerceEventBroker } from "./commerce-broker.js";
+import {
+  NAVIGATION_KINDS,
+  type ApprovedMarketingActionName,
+  type NavigationKind,
+} from "./events.js";
+import type { ContractViolation } from "./result.js";
+import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+import {
+  emitManagedActionActivated,
+  emitManagedPageView,
+  pageViewOwnerForNavigation,
+  type ManagedActionActivationInput,
+  type ManagedAnalyticsEmitResult,
+  type ManagedPageViewInput,
+} from "./managed-analytics.js";
+
+/** One explicit activation raised at a platform component's semantic handler. */
+export interface PlatformManagedActionActivation
+  extends Omit<ManagedActionActivationInput, "name"> {
+  /** One of the program-approved v1 identifiers; labels and selectors are not accepted. */
+  name: ApprovedMarketingActionName;
+}
+
+/**
+ * Optional platform-owned activation bus. It is an injected typed seam, not a browser
+ * event or DOM-discovery surface. The returned function must remove this listener.
+ */
+export interface PlatformManagedActionSource {
+  subscribe(listener: (activation: PlatformManagedActionActivation) => void): () => void;
+}
+
+export interface ManagedAnalyticsNavigationCommit extends ManagedPageViewInput {
+  kind: NavigationKind;
+  /** An aborted navigation never became a viewed resource. */
+  aborted?: boolean;
+}
+
+export type ManagedAnalyticsBridgeSkipReason =
+  | "already-initialized"
+  | "lifecycle-unchanged"
+  | "not-initialized"
+  | "not-page-view-owner"
+  | "disposed";
+
+export interface ManagedAnalyticsBridgeSkipped {
+  ok: true;
+  emitted: false;
+  skipReason: ManagedAnalyticsBridgeSkipReason;
+  deliveries: [];
+}
+
+export type ManagedAnalyticsBridgeResult =
+  | ManagedAnalyticsEmitResult
+  | ManagedAnalyticsBridgeSkipped;
+
+export interface ManagedAnalyticsEventBrokerBridgeOptions {
+  /** The existing versioned broker; this bridge never constructs a parallel bus. */
+  broker: CommerceEventBroker;
+  /** Optional typed source for platform-owned action handler activations. */
+  actionSource?: PlatformManagedActionSource;
+}
+
+type BridgeState = "idle" | "initializing" | "initialized" | "disposed";
+
+function skipped(skipReason: ManagedAnalyticsBridgeSkipReason): ManagedAnalyticsBridgeSkipped {
+  return { ok: true, emitted: false, skipReason, deliveries: [] };
+}
+
+const PLATFORM_ACTION_FIELDS = ["logicalId", "name", "correlation", "sequence"] as const;
+const DOCUMENT_PAGE_FIELDS = ["logicalId", "path", "correlation", "attribution", "sequence"] as const;
+const NAVIGATION_FIELDS = [...DOCUMENT_PAGE_FIELDS, "kind", "aborted"] as const;
+
+function failure(
+  path: string,
+  code: string,
+  message: string,
+): { ok: false; violations: ContractViolation[] } {
+  return { ok: false, violations: [{ path, code, message }] };
+}
+
+/** Validate only bridge-owned top-level shape and value canaries; the broker validates the envelope. */
+function bridgeInputViolations(
+  input: unknown,
+  allowed: readonly string[],
+  label: string,
+): ContractViolation[] {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return [{ path: "(root)", code: "type", message: `${label} must be an object.` }];
+  }
+  const record = input as Record<string, unknown>;
+  if (Object.keys(record).some((key) => !allowed.includes(key))) {
+    return [{
+      path: "(root)",
+      code: "unknown_field",
+      message: `${label} contains a field outside its closed public contract.`,
+    }];
+  }
+
+  const violations: ContractViolation[] = [];
+  if (resemblesManagedAnalyticsPii(record["logicalId"])) {
+    violations.push({
+      path: "logicalId",
+      code: "pii_value",
+      message: "Logical ids must be opaque and cannot resemble customer PII.",
+    });
+  }
+  if (resemblesManagedAnalyticsPii(record["path"])) {
+    violations.push({
+      path: "path",
+      code: "pii_value",
+      message: "Page paths cannot contain values resembling customer PII.",
+    });
+  }
+  const correlation = record["correlation"];
+  if (
+    typeof correlation === "object" &&
+    correlation !== null &&
+    !Array.isArray(correlation) &&
+    resemblesManagedAnalyticsPii((correlation as Record<string, unknown>)["id"])
+  ) {
+    violations.push({
+      path: "correlation.id",
+      code: "pii_value",
+      message: "Correlation ids must be opaque and cannot resemble customer PII.",
+    });
+  }
+  return violations;
+}
+
+function invalidNavigationKind(): { ok: false; violations: ContractViolation[] } {
+  return {
+    ok: false,
+    violations: [
+      {
+        path: "kind",
+        code: "unknown_enum",
+        message: `Navigation kind must be one of: ${NAVIGATION_KINDS.join(", ")}.`,
+      },
+    ],
+  };
+}
+
+/**
+ * One bridge instance belongs to one traditional document.
+ *
+ * `initialize` emits the document-owned page view and binds the optional platform
+ * action source exactly once. Consent changes do not rebind or reinitialize it: the
+ * broker reads its current consent source at every later emission. A same-document
+ * route commit can emit its page view through {@link navigationCommitted}; document
+ * navigations remain owned by the destination document bootstrap, while hash moves
+ * and aborts are never page views. `dispose` is idempotent and terminal.
+ */
+export class ManagedAnalyticsEventBrokerBridge {
+  private state: BridgeState = "idle";
+  private unsubscribeActions?: () => void;
+  private readonly broker: CommerceEventBroker;
+  private readonly actionSource?: PlatformManagedActionSource;
+
+  constructor(options: ManagedAnalyticsEventBrokerBridgeOptions) {
+    this.broker = options.broker;
+    this.actionSource = options.actionSource;
+  }
+
+  get isInitialized(): boolean {
+    return this.state === "initialized";
+  }
+
+  get isDisposed(): boolean {
+    return this.state === "disposed";
+  }
+
+  /**
+   * Bind this document once and emit its bootstrap-owned page view. Repeated calls —
+   * including a mistaken consent-change re-init — neither subscribe nor emit again.
+   */
+  initialize(page: ManagedPageViewInput): ManagedAnalyticsBridgeResult {
+    if (this.state === "disposed") return skipped("disposed");
+    if (this.state !== "idle") return skipped("already-initialized");
+
+    try {
+      const violations = bridgeInputViolations(page, DOCUMENT_PAGE_FIELDS, "Document page input");
+      if (violations.length > 0) return { ok: false, violations };
+    } catch {
+      return failure(
+        "(root)",
+        "input_access_failed",
+        "Document page input could not be read safely.",
+      );
+    }
+
+    this.state = "initializing";
+    if (this.actionSource) {
+      try {
+        const unsubscribe = this.actionSource.subscribe((activation) => {
+          try {
+            // The result is intentionally ignored: analytics never breaks the action.
+            this.activate(activation);
+          } catch {
+            // A hostile collaborator/proxy cannot escape the platform-owned listener.
+          }
+        });
+        if (typeof unsubscribe !== "function") throw new TypeError("invalid unsubscribe");
+        this.unsubscribeActions = unsubscribe;
+      } catch {
+        this.state = "idle";
+        return failure(
+          "actionSource",
+          "source_subscribe_failed",
+          "The platform action source could not be bound.",
+        );
+      }
+    }
+
+    try {
+      const result = emitManagedPageView(this.broker, page);
+      if (!result.ok) {
+        return this.rollbackInitialization() ?? result;
+      }
+      this.state = "initialized";
+      return result;
+    } catch {
+      return this.rollbackInitialization() ?? failure(
+        "initialize",
+        "bridge_initialization_failed",
+        "Managed analytics initialization failed safely.",
+      );
+    }
+  }
+
+  /**
+   * Consent changes are intentionally an in-place no-op for bridge lifecycle. The
+   * broker consults its live consent snapshot on every future activation/navigation.
+   */
+  consentUpdated(): ManagedAnalyticsBridgeResult {
+    if (this.state === "disposed") return skipped("disposed");
+    if (this.state !== "initialized") return skipped("not-initialized");
+    return skipped("lifecycle-unchanged");
+  }
+
+  /** Emit an explicitly named platform action through the existing broker. */
+  activate(activation: PlatformManagedActionActivation): ManagedAnalyticsBridgeResult {
+    if (this.state === "disposed") return skipped("disposed");
+    if (this.state !== "initialized") return skipped("not-initialized");
+
+    let projected: ManagedActionActivationInput;
+    try {
+      const violations = bridgeInputViolations(
+        activation,
+        PLATFORM_ACTION_FIELDS,
+        "Platform action activation",
+      );
+      if (violations.length > 0) return { ok: false, violations };
+      projected = {
+        logicalId: activation.logicalId,
+        name: activation.name,
+        correlation: activation.correlation,
+        ...(activation.sequence !== undefined ? { sequence: activation.sequence } : {}),
+      };
+    } catch {
+      return failure(
+        "(root)",
+        "input_access_failed",
+        "Platform action activation could not be read safely.",
+      );
+    }
+
+    try {
+      return emitManagedActionActivated(this.broker, projected);
+    } catch {
+      return failure(
+        "activate",
+        "action_emit_failed",
+        "Managed action emission failed safely.",
+      );
+    }
+  }
+
+  /**
+   * Emit the page view owned by a committed same-document route. Full-document loads
+   * are counted by the new document's `initialize`; hashes and aborts are not views.
+   */
+  navigationCommitted(
+    navigation: ManagedAnalyticsNavigationCommit,
+  ): ManagedAnalyticsBridgeResult {
+    if (this.state === "disposed") return skipped("disposed");
+    if (this.state !== "initialized") return skipped("not-initialized");
+
+    let page: ManagedPageViewInput;
+    let kind: NavigationKind;
+    let aborted: boolean | undefined;
+    try {
+      const violations = bridgeInputViolations(
+        navigation,
+        NAVIGATION_FIELDS,
+        "Navigation commit",
+      );
+      if (violations.length > 0) return { ok: false, violations };
+      if (!(NAVIGATION_KINDS as readonly unknown[]).includes(navigation.kind)) {
+        return invalidNavigationKind();
+      }
+      kind = navigation.kind;
+      aborted = navigation.aborted;
+      page = {
+        logicalId: navigation.logicalId,
+        path: navigation.path,
+        correlation: navigation.correlation,
+        ...(navigation.attribution ? { attribution: navigation.attribution } : {}),
+        ...(navigation.sequence !== undefined ? { sequence: navigation.sequence } : {}),
+      };
+    } catch {
+      return failure(
+        "(root)",
+        "input_access_failed",
+        "Navigation commit could not be read safely.",
+      );
+    }
+    if (pageViewOwnerForNavigation(kind, aborted) !== "navigation-commit") {
+      return skipped("not-page-view-owner");
+    }
+    try {
+      return emitManagedPageView(this.broker, page);
+    } catch {
+      return failure(
+        "navigation",
+        "page_emit_failed",
+        "Managed page emission failed safely.",
+      );
+    }
+  }
+
+  /** Remove the typed platform source listener once; disposal is terminal. */
+  dispose(): ManagedAnalyticsBridgeResult {
+    if (this.state === "disposed" && !this.unsubscribeActions) return skipped("disposed");
+    this.state = "disposed";
+    const unbindFailure = this.unbindActions();
+    return unbindFailure ?? skipped("lifecycle-unchanged");
+  }
+
+  private rollbackInitialization(): ManagedAnalyticsBridgeResult | null {
+    const unbindFailure = this.unbindActions();
+    // A listener whose removal could not be proven remains owned by this bridge.
+    // Stay terminal so a corrected initialize cannot stack another listener; a
+    // later dispose may retry the retained teardown.
+    this.state = unbindFailure ? "disposed" : "idle";
+    return unbindFailure;
+  }
+
+  private unbindActions(): ManagedAnalyticsBridgeResult | null {
+    const unsubscribe = this.unsubscribeActions;
+    if (!unsubscribe) return null;
+    try {
+      unsubscribe();
+      this.unsubscribeActions = undefined;
+      return null;
+    } catch {
+      return failure(
+        "actionSource",
+        "source_unsubscribe_failed",
+        "The platform action source could not be unbound cleanly.",
+      );
+    }
+  }
+}
+
+/** Convenience factory for hosts that prefer a function over `new`. */
+export function createManagedAnalyticsEventBrokerBridge(
+  options: ManagedAnalyticsEventBrokerBridgeOptions,
+): ManagedAnalyticsEventBrokerBridge {
+  return new ManagedAnalyticsEventBrokerBridge(options);
+}

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

@@ -0,0 +1,14 @@
+/** Shared PII-value canary for managed browser events and their diagnostics. */
+import { MANAGED_ANALYTICS_PII_VALUE_PATTERN } from "./managed-analytics-api-v1-safety.mjs";
+
+const MANAGED_ANALYTICS_PII_VALUE = new RegExp(MANAGED_ANALYTICS_PII_VALUE_PATTERN);
+
+/** 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);
+}
+
+/** Defense-in-depth for identifiers copied into structured broker observations. */
+export function safeManagedAnalyticsDiagnosticId(value: string): string {
+  return resemblesManagedAnalyticsPii(value) ? "[redacted]" : value;
+}

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

@@ -0,0 +1,277 @@
+/**
+ * Storefront-managed analytics semantics.
+ *
+ * This module is deliberately DOM-free. Platform components call the named emit
+ * functions at the semantic action boundary; the runtime never discovers actions by
+ * inspecting selectors, text, classes, forms, globals, or a dataLayer. Tenant and
+ * environment are stamped by CommerceEventBroker's trusted construction context.
+ */
+import {
+  reqArray,
+  reqLiteral,
+  reqObject,
+  reqString,
+  rejectUnknownKeys,
+  Violations,
+  type ContractResult,
+} from "./result.js";
+import { findForbiddenFields } from "./secrets.js";
+import type { CommerceEmitResult, CommerceEventBroker } from "./commerce-broker.js";
+import {
+  APPROVED_MARKETING_ACTION_NAMES,
+  MARKETING_ACTION_NAME_PATTERN,
+  NAVIGATION_KINDS,
+  type ApprovedMarketingActionName,
+  type EventCorrelation,
+  type NavigationKind,
+} from "./events.js";
+
+export const TENANT_ACTION_REGISTRY_SCHEMA_VERSION = 1 as const;
+
+/**
+ * Stable action identifiers are authored data, not labels. The `_mktg` suffix keeps
+ * marketing-program actions in a distinct namespace while allowing each tenant to
+ * register only the actions it actually renders.
+ */
+export const TENANT_MARKETING_ACTION_NAME_PATTERN = MARKETING_ACTION_NAME_PATTERN;
+
+export interface TenantAnalyticsAction {
+  name: ApprovedMarketingActionName;
+}
+
+/** The explicit, server-loaded action allowlist for one tenant. */
+export interface TenantActionRegistry {
+  schemaVersion: typeof TENANT_ACTION_REGISTRY_SCHEMA_VERSION;
+  actions: TenantAnalyticsAction[];
+}
+
+/**
+ * Validate an authored tenant registry fail-closed. Action declarations carry only a
+ * semantic name: DOM binding details and free-form payloads are not part of the
+ * contract, so they are rejected as unknown fields.
+ */
+export function validateTenantActionRegistry(input: unknown): ContractResult<TenantActionRegistry> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+  rejectUnknownKeys(obj, ["schemaVersion", "actions"], v, "");
+  reqLiteral(obj, "schemaVersion", TENANT_ACTION_REGISTRY_SCHEMA_VERSION, v, "");
+
+  const rawActions = reqArray(obj, "actions", v, "");
+  const actions: TenantAnalyticsAction[] = [];
+  if (rawActions) {
+    rawActions.forEach((raw, index) => {
+      const path = `actions[${index}]`;
+      const action = reqObject(raw, v, path);
+      if (!action) return;
+      rejectUnknownKeys(action, ["name"], v, path);
+      const name = reqString(action, "name", v, path);
+      if (name === undefined) return;
+      if (!TENANT_MARKETING_ACTION_NAME_PATTERN.test(name)) {
+        v.add(
+          `${path}.name`,
+          "format",
+          "Action name must be lowercase snake_case, end in _mktg, and contain no free-form text.",
+        );
+      } else if (!(APPROVED_MARKETING_ACTION_NAMES as readonly string[]).includes(name)) {
+        v.add(
+          `${path}.name`,
+          "unknown_enum",
+          "Action name is not in the approved v1 marketing action allowlist.",
+        );
+      }
+      actions.push({ name: name as ApprovedMarketingActionName });
+    });
+    const seen = new Set<string>();
+    actions.forEach((action, index) => {
+      if (seen.has(action.name)) {
+        v.add(
+          `actions[${index}].name`,
+          "duplicate",
+          "Duplicate action name; duplicates are rejected.",
+        );
+      }
+      seen.add(action.name);
+    });
+  }
+
+  for (const violation of findForbiddenFields(obj)) v.items.push(violation);
+  if (!v.ok) return { ok: false, violations: v.items };
+  return {
+    ok: true,
+    value: {
+      schemaVersion: TENANT_ACTION_REGISTRY_SCHEMA_VERSION,
+      actions,
+    },
+  };
+}
+
+/** A minimized attribution object; raw URLs never cross the analytics contract. */
+export interface ManagedPageAttribution {
+  referrer?: { origin: string };
+  utm?: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  };
+}
+
+export interface AttributionSourceInput {
+  /** Explicit renderer/runtime input. This module never reads document.referrer. */
+  referrerUrl?: string | null;
+  /** Explicit route URL used only to read allowlisted UTM keys. */
+  routeUrl?: string | null;
+}
+
+const UTM_QUERY_FIELDS = [
+  ["utm_source", "source"],
+  ["utm_medium", "medium"],
+  ["utm_campaign", "campaign"],
+  ["utm_term", "term"],
+  ["utm_content", "content"],
+] as const;
+const SAFE_CAMPAIGN_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+const PROTECTED_CAMPAIGN_TOKEN =
+  /(?:@|\d{7,}|(?:^|[._~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[._~-]))/i;
+
+function safeCampaignToken(value: string): string | undefined {
+  return SAFE_CAMPAIGN_TOKEN.test(value) && !PROTECTED_CAMPAIGN_TOKEN.test(value)
+    ? value
+    : undefined;
+}
+
+/**
+ * Reduce explicit URL inputs to an origin-only referrer and the five standard UTM
+ * tokens. Query keys outside the UTM allowlist, duplicate keys, unsafe free-form
+ * values, credentials, paths, and fragments are discarded. No browser global is read.
+ */
+export function minimizePageAttribution(input: AttributionSourceInput): ManagedPageAttribution | undefined {
+  const result: ManagedPageAttribution = {};
+
+  if (input.referrerUrl) {
+    try {
+      const referrer = new URL(input.referrerUrl);
+      if (
+        ["http:", "https:"].includes(referrer.protocol) &&
+        referrer.username === "" &&
+        referrer.password === ""
+      ) {
+        result.referrer = { origin: referrer.origin };
+      }
+    } catch {
+      // Invalid referrer input is omitted, never forwarded raw.
+    }
+  }
+
+  if (input.routeUrl) {
+    try {
+      const route = new URL(input.routeUrl, "https://route.invalid");
+      const utm: NonNullable<ManagedPageAttribution["utm"]> = {};
+      for (const [queryName, field] of UTM_QUERY_FIELDS) {
+        const values = route.searchParams.getAll(queryName);
+        if (values.length !== 1) continue;
+        const value = safeCampaignToken(values[0] ?? "");
+        if (value !== undefined) utm[field] = value;
+      }
+      if (Object.keys(utm).length > 0) result.utm = utm;
+    } catch {
+      // Invalid route input contributes no attribution.
+    }
+  }
+
+  return result.referrer || result.utm ? result : undefined;
+}
+
+export type ManagedAnalyticsEmitResult =
+  | CommerceEmitResult
+  | {
+      ok: true;
+      emitted: false;
+      skipReason: "consent-ineligible";
+      deliveries: [];
+    };
+
+function consentIneligible(): ManagedAnalyticsEmitResult {
+  return { ok: true, emitted: false, skipReason: "consent-ineligible", deliveries: [] };
+}
+
+export interface ManagedPageViewInput {
+  logicalId: string;
+  path: string;
+  correlation: EventCorrelation;
+  attribution?: ManagedPageAttribution;
+  sequence?: number;
+}
+
+/**
+ * Emit one page view at a semantic document/route commit. The path and optional
+ * minimized attribution are the complete data allowlist; title and DOM state are not
+ * accepted by this managed seam.
+ */
+export function emitManagedPageView(
+  broker: CommerceEventBroker,
+  input: ManagedPageViewInput,
+): ManagedAnalyticsEmitResult {
+  if (!broker.isConsentEligible("analytics")) return consentIneligible();
+  return broker.emit({
+    type: "storefront.page.viewed.v2",
+    logicalId: input.logicalId,
+    subject: "page",
+    correlation: input.correlation,
+    data: {
+      path: input.path,
+      ...(input.attribution ? { attribution: input.attribution } : {}),
+    },
+    ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+  });
+}
+
+export interface ManagedActionActivationInput {
+  logicalId: string;
+  name: string;
+  correlation: EventCorrelation;
+  sequence?: number;
+}
+
+/**
+ * Emit one explicitly registered semantic action. The caller supplies no tenant,
+ * environment, selector, label, destination, or arbitrary properties; the emitted
+ * data object is exactly `{ name }`.
+ */
+export function emitManagedActionActivated(
+  broker: CommerceEventBroker,
+  input: ManagedActionActivationInput,
+): ManagedAnalyticsEmitResult {
+  if (!broker.isConsentEligible("analytics")) return consentIneligible();
+  return broker.emit({
+    type: "storefront.action.activated.v1",
+    logicalId: input.logicalId,
+    subject: "action",
+    correlation: input.correlation,
+    data: { name: input.name },
+    ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+  });
+}
+
+/** Where the page-view paired with a completed navigation is emitted. */
+export type NavigationPageViewOwner = "document-bootstrap" | "navigation-commit" | "none";
+
+/**
+ * Page/navigation compatibility policy:
+ * - a full document navigation is counted once by the destination document bootstrap;
+ * - a committed same-document back/forward or redirect is counted at route commit;
+ * - a hash move emits the navigation lifecycle event but is not a new page view;
+ * - an aborted navigation emits neither event.
+ */
+export function pageViewOwnerForNavigation(
+  kind: NavigationKind,
+  aborted = false,
+): NavigationPageViewOwner {
+  if (aborted) return "none";
+  if (!(NAVIGATION_KINDS as readonly unknown[]).includes(kind)) return "none";
+  if (kind === "hash") return "none";
+  if (kind === "document") return "document-bootstrap";
+  return "navigation-commit";
+}