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

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

@@ -0,0 +1,497 @@
+/**
+ * The platform-owned browser commerce event broker (ADR 0014 M2
+ * `integration-commerce-data-minimized`, M3 `integration-events-dual-delivery`;
+ * ext-commerce-02). It is the single client-side seam between the storefront's own
+ * page/product/cart/handoff signals and the scoped subscribers — apps, sandboxed
+ * widget iframes, elevated-parent code — that want to measure them.
+ *
+ * It owns three properties that its callers do NOT get to override:
+ *
+ *   - SERVER-OWNED CONTEXT IS STAMPED, NEVER SUPPLIED. A caller hands the broker only
+ *     an anonymous, allowlisted `data` payload plus the logical action's identity
+ *     ({@link CommerceEmitInput}); the broker stamps `storefront.tenant`,
+ *     `environment`, `siteSurface`, `emitter: "browser"`, and the current consent
+ *     snapshot from the trusted execution context it was constructed with. Every
+ *     emitted envelope is then run through {@link validateCommerceEvent}, so the
+ *     closed field catalog rejects any PII, payment, order, or unknown field — a
+ *     privileged parent with DOM authority gains NO extra server-held data by that
+ *     authority, and a browser emitter can never author a server-authoritative
+ *     conversion (`forged_authority`).
+ *
+ *   - ONE EVENT PER LOGICAL ACTION. The broker deduplicates on the envelope's
+ *     {@link eventDedupeKey} (`id`): a second emit of the same logical id — a
+ *     double-fired DOM handler, a replay — collapses to a no-op, so a subscriber
+ *     registered once observes each logical action exactly once.
+ *
+ *   - SUBSCRIBER FAULTS ARE ISOLATED. Subscriptions are keyed by a stable id, so a
+ *     re-subscribe REPLACES rather than stacks (no duplicate listeners after a
+ *     consent/config update). Each subscriber is delivered inside its own try/catch
+ *     (the kernel-05 lifecycle isolation model), so a throwing subscriber cannot
+ *     break the cart, navigation, or any other subscriber, and the emit call returns
+ *     normally to its caller.
+ *
+ * Delivery is consent-filtered per subscriber: a subscriber declares the
+ * {@link ConsentPurpose} its destination depends on, and the broker withholds the
+ * event unless that purpose is eligible under the current snapshot
+ * ({@link isPurposeEligible}) — the same predicate the server destination filter and
+ * the browser destination loader share. A sandboxed iframe consumer receives the
+ * validated {@link CommerceEvent} as a TYPED, channel-tagged postMessage, never a raw
+ * ad-hoc message.
+ *
+ * DOM-free and dependency-injected (trusted context, a consent snapshot source, a
+ * clock), so it is edge-safe and fully testable in node; an iframe sink is the only
+ * browser-touching surface and is supplied by the caller.
+ */
+import type {
+  CommerceEvent,
+  CommerceEventType,
+  EventCorrelation,
+  TrustedEventContext,
+} from "./events.js";
+import {
+  EVENT_SOURCE_OF_TRUTH,
+  PURCHASE_COMPLETED_EVENT_TYPE,
+  eventDedupeKey,
+  validateCommerceEvent,
+} from "./events.js";
+import type { ConsentSnapshot } from "./consent-broker.js";
+import { isPurposeEligible, toEventConsentSnapshot } from "./consent-broker.js";
+import type { ConsentPurpose } from "../integration-capabilities.js";
+import { COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION } from "./version.js";
+import type { ContractViolation } from "./result.js";
+import { safeManagedAnalyticsDiagnosticId } from "./managed-analytics-value-safety.js";
+import {
+  validateTenantActionRegistry,
+  type TenantActionRegistry,
+} from "./managed-analytics.js";
+
+/** The channel tag every broker→iframe message carries; a consumer keys its parse on it. */
+export const COMMERCE_EVENT_MESSAGE_CHANNEL = "tot.commerce-event.v1" as const;
+
+/** The typed envelope the broker posts to an iframe consumer — never a bare event. */
+export interface CommerceEventMessage {
+  channel: typeof COMMERCE_EVENT_MESSAGE_CHANNEL;
+  event: CommerceEvent;
+}
+
+/**
+ * What a caller supplies to emit one logical browser commerce action. It carries the
+ * anonymous, allowlisted `data` and the action's identity ONLY — never the
+ * server-owned `storefront.*` context, which the broker stamps from its trusted
+ * construction context so it cannot be caller-forged.
+ */
+export interface CommerceEmitInput {
+  /** A browser source-of-truth event type; a server-authoritative type is refused. */
+  type: CommerceEventType;
+  /** The opaque logical event id — the dedupe key. The same logical action reuses it. */
+  logicalId: string;
+  /** Opaque in-event subject (e.g. an anonymous cart/item-set handle). */
+  subject: string;
+  /** The anonymous, field-allowlisted payload for this type. Validated on emit. */
+  data: Record<string, unknown>;
+  /** The bounded-lifetime attribution thread this action belongs to. */
+  correlation: EventCorrelation;
+  /** Optional per-emitter monotonic counter for out-of-order detection. */
+  sequence?: number;
+}
+
+/** The minimal postMessage surface a real sandboxed iframe `contentWindow` satisfies. */
+export interface CommerceEventPostTarget {
+  postMessage(message: CommerceEventMessage, targetOrigin: string): void;
+}
+
+/**
+ * Where a subscriber's events go:
+ *   - `callback` — an in-page handler invoked with the validated event.
+ *   - `iframe`   — a sandboxed consumer the broker posts a TYPED, channel-tagged
+ *     message to at a fixed `targetOrigin`, so the frame reads a validated event and
+ *     never a raw one.
+ */
+export type CommerceEventSink =
+  | { kind: "callback"; handler: (event: CommerceEvent) => void }
+  | { kind: "iframe"; frame: CommerceEventPostTarget; targetOrigin: string };
+
+/**
+ * One scoped subscription. `id` is its stable identity: subscribing again with the
+ * same id REPLACES the prior registration (no duplicate listeners). `types` is the
+ * app/topic scope; omitting it subscribes to every browser event type. `consentPurpose`
+ * is the destination's required purpose; omitting it means essential-only (always
+ * eligible).
+ */
+export interface CommerceEventSubscription {
+  id: string;
+  sink: CommerceEventSink;
+  types?: readonly CommerceEventType[];
+  consentPurpose?: ConsentPurpose;
+}
+
+/** Why a subscriber did not receive an emitted event (delivery is scoped + fail-soft). */
+export type SubscriberSkipReason = "out-of-scope" | "consent-ineligible" | "threw";
+
+/** The per-subscriber outcome of one emit — a throwing sink is recorded, never propagated. */
+export interface SubscriberDeliveryOutcome {
+  subscriberId: string;
+  delivered: boolean;
+  reason?: SubscriberSkipReason;
+  /** Stable diagnostic code; subscriber exception text and stacks are never copied. */
+  error?: "subscriber_threw";
+}
+
+/** Why an emit delivered to nobody without being an error (the envelope was fine). */
+export type EmitSkipReason = "duplicate" | "not-browser-authored";
+
+/** The result of one emit. `ok: false` carries the envelope's contract violations. */
+export type CommerceEmitResult =
+  | {
+      ok: true;
+      event: CommerceEvent;
+      /** False when the logical id was already emitted (deduplicated) — no re-fire. */
+      emitted: boolean;
+      skipReason?: EmitSkipReason;
+      deliveries: SubscriberDeliveryOutcome[];
+    }
+  | { ok: false; violations: ContractViolation[] };
+
+/** A structured, non-sensitive delivery signal for observability — never a payload or stack. */
+export interface CommerceBrokerObservation {
+  type: CommerceEventType;
+  logicalId: string;
+  subscriberId: string;
+  ok: boolean;
+  /** Stable diagnostic code; subscriber exception text and stacks are never observed. */
+  error?: "subscriber_threw";
+}
+
+export type CommerceBrokerObserver = (observation: CommerceBrokerObservation) => void;
+
+export interface CommerceEventBrokerOptions {
+  /** The trusted tenant/environment/surface stamped onto every envelope; never caller-set. */
+  trusted: TrustedEventContext;
+  /** The event `source` URN for this surface; server-owned, stamped from trusted context. */
+  source: string;
+  /** Reads the current consent snapshot at emit time (the neutral broker's snapshot). */
+  consentSnapshot: () => ConsentSnapshot;
+  /** Server-loaded explicit action registry for this tenant; absent/invalid fails action emission closed. */
+  tenantActionRegistry?: unknown;
+  /** ISO-8601 timestamp source; defaults to wall clock. */
+  now?: () => string;
+  /** Optional observer for delivery diagnostics (isolation faults surface here, not to callers). */
+  observe?: CommerceBrokerObserver;
+}
+
+const MANAGED_ANALYTICS_EVENT_TYPES: readonly CommerceEventType[] = [
+  "storefront.page.viewed.v2",
+  "storefront.action.activated.v1",
+];
+
+function isManagedAnalyticsEvent(type: CommerceEventType): boolean {
+  return MANAGED_ANALYTICS_EVENT_TYPES.includes(type);
+}
+
+export class CommerceEventBroker {
+  private readonly subscriptions = new Map<string, CommerceEventSubscription>();
+  private readonly emittedIds = new Set<string>();
+  private readonly opts: CommerceEventBrokerOptions;
+  private readonly tenantActionRegistry: TenantActionRegistry | null;
+  private readonly tenantActionRegistryViolations: ContractViolation[];
+
+  constructor(options: CommerceEventBrokerOptions) {
+    this.opts = options;
+    if (options.tenantActionRegistry === undefined) {
+      this.tenantActionRegistry = null;
+      this.tenantActionRegistryViolations = [];
+    } else {
+      const registry = validateTenantActionRegistry(options.tenantActionRegistry);
+      this.tenantActionRegistry = registry.ok ? registry.value : null;
+      this.tenantActionRegistryViolations = registry.ok ? [] : registry.violations;
+    }
+  }
+
+  /**
+   * Register (or REPLACE) a scoped subscription. Keying on `subscription.id` means a
+   * re-subscribe — e.g. after a consent change re-derives a destination — swaps the
+   * registration in place rather than stacking a second listener, so one logical
+   * action still fires the subscriber exactly once. Returns an unsubscribe function.
+   */
+  subscribe(subscription: CommerceEventSubscription): () => void {
+    this.subscriptions.set(subscription.id, subscription);
+    return () => {
+      const current = this.subscriptions.get(subscription.id);
+      // Only remove if this exact registration is still the live one; a later
+      // re-subscribe under the same id owns the slot and must not be torn down here.
+      if (current === subscription) this.subscriptions.delete(subscription.id);
+    };
+  }
+
+  /** Whether a subscriber id currently holds a registration. */
+  hasSubscriber(id: string): boolean {
+    return this.subscriptions.has(id);
+  }
+
+  /** Read destination eligibility from the broker's current trusted consent snapshot. */
+  isConsentEligible(purpose: ConsentPurpose): boolean {
+    return isPurposeEligible(this.opts.consentSnapshot(), purpose);
+  }
+
+  /**
+   * Emit one logical browser commerce action. The broker builds the envelope from the
+   * trusted context (the caller supplies no server-owned field), validates it against
+   * the closed contract, deduplicates on its logical id, and fans it out to every
+   * in-scope, consent-eligible subscriber inside per-subscriber isolation.
+   *
+   * A failed validation delivers to nobody and returns the violations. A duplicate
+   * logical id returns `emitted: false`. A subscriber that throws is recorded in its
+   * outcome and observed — never rethrown — so the caller (cart, navigation) is
+   * unaffected.
+   */
+  emit(input: CommerceEmitInput): CommerceEmitResult {
+    // Fail fast and clearly on a server-authoritative type before building an envelope
+    // the validator would reject anyway; the browser can never author a conversion.
+    if (EVENT_SOURCE_OF_TRUTH[input.type] !== "browser") {
+      return {
+        ok: false,
+        violations: [
+          {
+            path: "type",
+            code: "forged_authority",
+            message: `"${input.type}" is server-authoritative; the browser broker cannot emit it.`,
+          },
+        ],
+      };
+    }
+
+    const snapshot = this.opts.consentSnapshot();
+    const envelope: CommerceEvent = {
+      specversion: "1.0",
+      id: input.logicalId,
+      source: this.opts.source,
+      type: input.type,
+      subject: input.subject,
+      time: this.now(),
+      datacontenttype: "application/json",
+      storefront: {
+        schemaVersion: COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION,
+        tenant: this.opts.trusted.tenant,
+        environment: this.opts.trusted.environment,
+        siteSurface: this.opts.trusted.siteSurface,
+        emitter: "browser",
+        ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+      },
+      correlation: input.correlation,
+      consent: toEventConsentSnapshot(snapshot),
+      data: input.data,
+    };
+
+    const validation = validateCommerceEvent(envelope);
+    if (!validation.ok) return { ok: false, violations: validation.violations };
+    const event = validation.value;
+
+    if (event.type === "storefront.action.activated.v1") {
+      if (!this.tenantActionRegistry) {
+        return {
+          ok: false,
+          violations:
+            this.tenantActionRegistryViolations.length > 0
+              ? this.tenantActionRegistryViolations
+              : [
+                  {
+                    path: "data.name",
+                    code: "unregistered_action",
+                    message: "Managed actions require a valid tenant action registry.",
+                  },
+                ],
+        };
+      }
+      const actionName = event.data["name"] as string;
+      if (!this.tenantActionRegistry.actions.some((action) => action.name === actionName)) {
+        return {
+          ok: false,
+          violations: [
+            {
+              path: "data.name",
+              code: "unregistered_action",
+              message: "Action is not present in the tenant's explicit action registry.",
+            },
+          ],
+        };
+      }
+    }
+
+    if (isManagedAnalyticsEvent(event.type) && !isPurposeEligible(snapshot, "analytics")) {
+      return {
+        ok: false,
+        violations: [
+          {
+            path: "consent.eligiblePurposes",
+            code: "consent_ineligible",
+            message: "Managed analytics events require analytics consent before creation or delivery.",
+          },
+        ],
+      };
+    }
+
+    const key = eventDedupeKey(event);
+    if (this.emittedIds.has(key)) {
+      return { ok: true, event, emitted: false, skipReason: "duplicate", deliveries: [] };
+    }
+    this.emittedIds.add(key);
+
+    const deliveries: SubscriberDeliveryOutcome[] = [];
+    for (const subscription of this.subscriptions.values()) {
+      deliveries.push(this.deliver(subscription, event, snapshot));
+    }
+    return { ok: true, event, emitted: true, deliveries };
+  }
+
+  private deliver(
+    subscription: CommerceEventSubscription,
+    event: CommerceEvent,
+    snapshot: ConsentSnapshot,
+  ): SubscriberDeliveryOutcome {
+    if (subscription.types && !subscription.types.includes(event.type)) {
+      return { subscriberId: subscription.id, delivered: false, reason: "out-of-scope" };
+    }
+    if (
+      isManagedAnalyticsEvent(event.type) &&
+      subscription.consentPurpose !== "analytics"
+    ) {
+      return { subscriberId: subscription.id, delivered: false, reason: "consent-ineligible" };
+    }
+    // essential is always eligible, so an undeclared purpose always passes.
+    const purpose = subscription.consentPurpose ?? "essential";
+    if (!isPurposeEligible(snapshot, purpose)) {
+      return { subscriberId: subscription.id, delivered: false, reason: "consent-ineligible" };
+    }
+
+    try {
+      this.dispatch(subscription.sink, event);
+      this.observe({
+        type: event.type,
+        logicalId: event.id,
+        subscriberId: subscription.id,
+        ok: true,
+      });
+      return { subscriberId: subscription.id, delivered: true };
+    } catch {
+      this.observe({
+        type: event.type,
+        logicalId: event.id,
+        subscriberId: subscription.id,
+        ok: false,
+        error: "subscriber_threw",
+      });
+      return {
+        subscriberId: subscription.id,
+        delivered: false,
+        reason: "threw",
+        error: "subscriber_threw",
+      };
+    }
+  }
+
+  private dispatch(sink: CommerceEventSink, event: CommerceEvent): void {
+    if (sink.kind === "callback") {
+      sink.handler(event);
+      return;
+    }
+    // A sandboxed consumer gets a TYPED, channel-tagged, already-validated envelope.
+    sink.frame.postMessage({ channel: COMMERCE_EVENT_MESSAGE_CHANNEL, event }, sink.targetOrigin);
+  }
+
+  private now(): string {
+    return this.opts.now ? this.opts.now() : new Date().toISOString();
+  }
+
+  private observe(observation: CommerceBrokerObservation): void {
+    try {
+      this.opts.observe?.(Object.freeze({
+        ...observation,
+        logicalId: safeManagedAnalyticsDiagnosticId(observation.logicalId),
+        subscriberId: safeManagedAnalyticsDiagnosticId(observation.subscriberId),
+      }));
+    } catch {
+      // Observability is fail-soft: a broken collaborator never changes delivery.
+    }
+  }
+}
+
+/**
+ * The iframe-consumer side of the channel: read a received postMessage payload
+ * FAIL-CLOSED into a validated {@link CommerceEvent}. A payload without the exact
+ * broker channel tag, or one whose event does not pass {@link validateCommerceEvent},
+ * yields `null` — a consumer never acts on a raw, forged, or off-channel message.
+ */
+export function parseCommerceEventMessage(data: unknown): CommerceEvent | null {
+  if (typeof data !== "object" || data === null) return null;
+  const record = data as Record<string, unknown>;
+  if (record["channel"] !== COMMERCE_EVENT_MESSAGE_CHANNEL) return null;
+  const result = validateCommerceEvent(record["event"]);
+  return result.ok ? result.value : null;
+}
+
+/**
+ * The anonymous, minimized post-purchase summary a browser subscriber may receive
+ * (ADR 0014 M2 `integration-commerce-data-minimized`): currency, total value, item
+ * count, and anonymous line items. It carries NO order id, customer identity, payment
+ * data, or signed-cart material — the authoritative financial record lives only on the
+ * server verified-order path. The broker's closed field catalog re-enforces this on emit.
+ */
+export interface PurchaseCompletedSummary {
+  currency: string;
+  /** A non-negative decimal money string, e.g. `"42.50"`. */
+  value: string;
+  itemCount: number;
+  items: readonly {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    unitPrice: string;
+  }[];
+}
+
+/**
+ * The ONE named seam a post-purchase third-party trigger flows through: emit the
+ * browser-deliverable `storefront.purchase.completed.v1` signal (design-partner finding
+ * F1/F2 wire). It rides the broker's existing guarantees verbatim — server-owned context
+ * stamped not caller-set, one-event-per-logical-action dedupe, per-subscriber consent
+ * filtering, and subscriber-fault isolation — so a scoped sandbox subscriber (via the
+ * lifecycle context's receive-only subscribe handle) reacts to a completed purchase
+ * exactly once. The caller supplies only the anonymous summary and the logical action
+ * identity; it can never set a server-owned field or author a verified-provider order.
+ *
+ * NOTE ON THE LIVE TRIGGER (honest gap): the storefront's checkout AND receipt are
+ * provider-hosted and cross-domain (Foxy), so there is no storefront-rendered
+ * confirmation page in THIS origin to call this seam from today. The subscribe/validate
+ * path is fully wired and this emit seam is real and tested; the remaining work is the
+ * cross-domain bridge that carries the provider receipt signal back to a storefront-origin
+ * document which then calls this — tracked as an explicit follow-up, not faked here.
+ */
+export function emitPurchaseCompleted(
+  broker: CommerceEventBroker,
+  input: {
+    /** The opaque logical event id — the dedupe key. The same completed purchase reuses it. */
+    logicalId: string;
+    /** Opaque in-event subject (e.g. an anonymous purchase/session handle) — never an order id. */
+    subject: string;
+    /** The bounded-lifetime attribution thread this purchase belongs to. */
+    correlation: EventCorrelation;
+    /** The anonymous, PII-free purchase summary. */
+    summary: PurchaseCompletedSummary;
+    /** Optional per-emitter monotonic counter for out-of-order detection. */
+    sequence?: number;
+  },
+): CommerceEmitResult {
+  return broker.emit({
+    type: PURCHASE_COMPLETED_EVENT_TYPE,
+    logicalId: input.logicalId,
+    subject: input.subject,
+    correlation: input.correlation,
+    data: {
+      currency: input.summary.currency,
+      value: input.summary.value,
+      itemCount: input.summary.itemCount,
+      items: input.summary.items.map((item) => ({ ...item })),
+    },
+    ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+  });
+}