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

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

@@ -0,0 +1,337 @@
+/**
+ * The neutral consent broker — one source of truth for consent purposes, default
+ * state, CMP updates, and destination eligibility across BOTH the browser and the
+ * server (ADR 0022 `receipt-consent-propagation`, ADR 0023 Q3
+ * `analytics-consent-required`; ext-policy-03).
+ *
+ * It sits on the closed capability model's {@link CONSENT_PURPOSES} vocabulary and
+ * produces the versioned {@link ConsentSnapshot} that everything downstream filters
+ * against — the browser destination loader, the server destination filter, and the
+ * commerce event envelope's {@link EventConsentSnapshot}. It also emits the default
+ * snapshot kernel-04's `consent.defaults` render phase inlines, so consent defaults
+ * exist before any vendor loader runs.
+ *
+ * Fail-closed by construction:
+ *   - `essential` is the only always-eligible purpose and can never be gated off.
+ *   - Every other purpose is denied until the TENANT approves it exists AND an
+ *     affirmative decision (a native banner or a CMP) grants it — a manifest that
+ *     merely declares a dependent purpose cannot self-approve.
+ *   - An unknown or unapproved purpose can never make a non-essential destination
+ *     eligible; unknown state blocks.
+ *   - A CMP's disappearance reverts its grants to deny: removing a CMP defaults to
+ *     deny, never a silent grant.
+ *
+ * The snapshot is a pure function of (approved purposes, effective decisions), in
+ * canonical purpose order, so a broker driven by identical inputs on the server and
+ * in the browser yields a byte-identical snapshot (including `snapshotId`) — one
+ * versioned snapshot, not two that must be kept in sync.
+ */
+import { CONSENT_PURPOSES, type ConsentPurpose } from "../integration-capabilities.js";
+import { CONSENT_SNAPSHOT_SCHEMA_VERSION } from "./version.js";
+import type { EventConsentSnapshot } from "./events.js";
+
+/** The purpose that is always on and cannot be gated (charter floor). */
+const ESSENTIAL: ConsentPurpose = "essential";
+
+/** A tenant's approval decision for one purpose. */
+export type ConsentLegalBasis = "consent" | "legitimate-interest";
+
+/** One purpose the tenant has approved to exist, with its declared legal basis. */
+export interface TenantPurposeApproval {
+  purpose: ConsentPurpose;
+  legalBasis: ConsentLegalBasis;
+}
+
+/**
+ * The tenant's consent policy: which non-essential purposes exist at all. A purpose
+ * absent from this list can never become eligible, whatever a manifest declares or a
+ * CMP reports. `essential` is always approved implicitly.
+ */
+export interface TenantConsentPolicy {
+  purposes: readonly TenantPurposeApproval[];
+}
+
+/** A per-purpose consent outcome. */
+export type ConsentDecision = "granted" | "denied";
+
+/**
+ * The report a Consent Management Platform hands the broker. `decisions` is a
+ * partial map — a purpose the CMP does not mention stays at its prior state, never
+ * defaulting to granted.
+ */
+export interface CmpConsentReport {
+  cmpId: string;
+  decisions: Partial<Record<ConsentPurpose, ConsentDecision>>;
+}
+
+/**
+ * The CMP adapter contract: a neutral read seam over any concrete CMP. `read`
+ * returning `null` means the CMP is absent/not-yet-loaded — the broker treats that
+ * as no CMP grants, never as consent.
+ */
+export interface CmpAdapter {
+  readonly id: string;
+  read(): CmpConsentReport | null;
+}
+
+/**
+ * A dependent destination whose runtime effect requires a purpose. Its `load` runs
+ * once, deferred until the destination is first eligible (so it can never run under
+ * the default-deny snapshot); `onWithdraw` fires when a previously-eligible
+ * destination loses eligibility so it can stop future events and push any supported
+ * vendor update; `onResume` fires if it later becomes eligible again, so a change
+ * updates rather than re-initializes it.
+ */
+export interface ConsentDestination {
+  id: string;
+  purpose: ConsentPurpose;
+  load(): void;
+  onWithdraw?(snapshot: ConsentSnapshot): void;
+  onResume?(snapshot: ConsentSnapshot): void;
+}
+
+/**
+ * The versioned, browser-safe consent snapshot — the single value client and server
+ * destinations filter against. `eligiblePurposes` is in canonical purpose order and
+ * always contains `essential`. `unknownState` is always `"block"` (fail closed).
+ */
+export interface ConsentSnapshot {
+  schemaVersion: typeof CONSENT_SNAPSHOT_SCHEMA_VERSION;
+  snapshotId: string;
+  eligiblePurposes: ConsentPurpose[];
+  unknownState: "block";
+}
+
+/** FNV-1a 32-bit hex over an ASCII/UTF-16 string — a synchronous content digest, not a security boundary. */
+function fnv1a32Hex(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    const code = input.charCodeAt(i);
+    h = Math.imul(h ^ (code & 0xff), 0x01000193);
+    h = Math.imul(h ^ ((code >> 8) & 0xff), 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/** Content-addressed snapshot id: identical eligibility → identical id on client and server. */
+function computeSnapshotId(eligible: readonly ConsentPurpose[]): string {
+  return `cs1-${fnv1a32Hex(`${CONSENT_SNAPSHOT_SCHEMA_VERSION}:${eligible.join(",")}`)}`;
+}
+
+/** Build a snapshot from an eligible set, forcing `essential` on and canonicalizing order. */
+function makeSnapshot(eligible: Iterable<ConsentPurpose>): ConsentSnapshot {
+  const set = new Set<ConsentPurpose>(eligible);
+  set.add(ESSENTIAL);
+  const eligiblePurposes = CONSENT_PURPOSES.filter((p) => set.has(p));
+  return {
+    schemaVersion: CONSENT_SNAPSHOT_SCHEMA_VERSION,
+    snapshotId: computeSnapshotId(eligiblePurposes),
+    eligiblePurposes,
+    unknownState: "block",
+  };
+}
+
+/**
+ * The default consent snapshot kernel-04's `consent.defaults` phase inlines: only
+ * `essential` is eligible; every measurement purpose is denied until affirmatively
+ * granted. This is what precedes every vendor loader.
+ */
+export function defaultConsentSnapshot(): ConsentSnapshot {
+  return makeSnapshot([ESSENTIAL]);
+}
+
+/**
+ * Whether a purpose is currently eligible. `essential` is always eligible; an
+ * unknown or unapproved-and-ungranted purpose is not — so this both permits
+ * essential destinations and blocks non-essential ones under unknown state.
+ */
+export function isPurposeEligible(snapshot: ConsentSnapshot, purpose: string): boolean {
+  return snapshot.eligiblePurposes.includes(purpose as ConsentPurpose);
+}
+
+/**
+ * Server destination filter: keep only the destinations whose required purpose is
+ * eligible under `snapshot`. The browser loader and the server share this predicate,
+ * so a purpose withdrawn client-side stops the matching server destination too.
+ */
+export function filterDestinationsByConsent<T extends { purpose: ConsentPurpose }>(
+  snapshot: ConsentSnapshot,
+  destinations: readonly T[],
+): T[] {
+  return destinations.filter((d) => isPurposeEligible(snapshot, d.purpose));
+}
+
+/** Project a broker snapshot onto the commerce event envelope's consent reference. */
+export function toEventConsentSnapshot(snapshot: ConsentSnapshot): EventConsentSnapshot {
+  return {
+    schemaVersion: snapshot.schemaVersion,
+    snapshotId: snapshot.snapshotId,
+    eligiblePurposes: [...snapshot.eligiblePurposes],
+  };
+}
+
+/** Serialize a snapshot for inlining/transport. */
+export function serializeConsentSnapshot(snapshot: ConsentSnapshot): string {
+  return JSON.stringify(snapshot);
+}
+
+/**
+ * Parse a serialized snapshot fail-closed: an unknown schema version, a non-block
+ * unknown state, an unknown purpose, a missing `essential`, or an id that does not
+ * match the eligible set yields `null` — a caller cannot smuggle in a forged or
+ * tampered snapshot.
+ */
+export function parseConsentSnapshot(raw: unknown): ConsentSnapshot | null {
+  let obj: unknown = raw;
+  if (typeof raw === "string") {
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof obj !== "object" || obj === null) return null;
+  const s = obj as Record<string, unknown>;
+  if (s["schemaVersion"] !== CONSENT_SNAPSHOT_SCHEMA_VERSION) return null;
+  if (s["unknownState"] !== "block") return null;
+  if (typeof s["snapshotId"] !== "string") return null;
+  const eligibleRaw = s["eligiblePurposes"];
+  if (!Array.isArray(eligibleRaw)) return null;
+  const known = new Set<string>(CONSENT_PURPOSES);
+  for (const p of eligibleRaw) {
+    if (typeof p !== "string" || !known.has(p)) return null;
+  }
+  const eligible = CONSENT_PURPOSES.filter((p) => (eligibleRaw as string[]).includes(p));
+  if (!eligible.includes(ESSENTIAL)) return null;
+  const canonical = makeSnapshot(eligible);
+  if (canonical.snapshotId !== s["snapshotId"]) return null;
+  return canonical;
+}
+
+/** Listener invoked with the new snapshot whenever eligibility changes. */
+export type ConsentListener = (snapshot: ConsentSnapshot) => void;
+
+/**
+ * The neutral consent broker instance. ONE instance is the single source of truth
+ * for a page/request; CMP and native-banner updates mutate it in place (they never
+ * re-initialize it), so `snapshotId` advances while destinations keep their
+ * identity. Constructed identically on the server and in the browser, so both
+ * derive the same versioned snapshot.
+ */
+export class ConsentBroker {
+  private readonly approved = new Map<ConsentPurpose, ConsentLegalBasis>();
+  private readonly directDecisions = new Map<ConsentPurpose, ConsentDecision>();
+  private cmpDecisions = new Map<ConsentPurpose, ConsentDecision>();
+  private readonly destinations = new Map<string, ConsentDestination>();
+  private readonly loaded = new Set<string>();
+  private readonly active = new Set<string>();
+  private readonly listeners = new Set<ConsentListener>();
+  private snapshot: ConsentSnapshot;
+
+  constructor(policy: TenantConsentPolicy) {
+    for (const approval of policy.purposes) {
+      if (approval.purpose === ESSENTIAL) continue; // essential is implicit
+      this.approved.set(approval.purpose, approval.legalBasis);
+    }
+    this.snapshot = this.compute();
+  }
+
+  /** The current snapshot — the value client and server destinations filter against. */
+  getSnapshot(): ConsentSnapshot {
+    return this.snapshot;
+  }
+
+  /** Whether a purpose is currently eligible under this broker's snapshot. */
+  isEligible(purpose: string): boolean {
+    return isPurposeEligible(this.snapshot, purpose);
+  }
+
+  /** The legal basis the tenant approved for a purpose, or `undefined` if unapproved. */
+  legalBasisFor(purpose: ConsentPurpose): ConsentLegalBasis | undefined {
+    return this.approved.get(purpose);
+  }
+
+  /**
+   * Apply a CMP report, or `null` when the CMP is removed/absent. A report merges the
+   * CMP layer; `null` clears it entirely, so any purpose that was eligible only via
+   * the CMP reverts to denied. Removing a CMP never grants. Reuses this instance.
+   */
+  applyCmp(report: CmpConsentReport | null): ConsentSnapshot {
+    if (report === null) {
+      this.cmpDecisions = new Map();
+    } else {
+      for (const [purpose, decision] of Object.entries(report.decisions)) {
+        if (decision) this.cmpDecisions.set(purpose as ConsentPurpose, decision);
+      }
+    }
+    return this.update();
+  }
+
+  /**
+   * Apply an explicit decision layer (e.g. a native consent banner). A shopper's
+   * explicit choice overrides the CMP layer. Reuses this instance.
+   */
+  setDecisions(decisions: Partial<Record<ConsentPurpose, ConsentDecision>>): ConsentSnapshot {
+    for (const [purpose, decision] of Object.entries(decisions)) {
+      if (decision) this.directDecisions.set(purpose as ConsentPurpose, decision);
+    }
+    return this.update();
+  }
+
+  /**
+   * Register a dependent destination. It loads immediately if already eligible,
+   * otherwise its `load` is deferred until it first becomes eligible — a destination
+   * registered under the default-deny snapshot does not run.
+   */
+  registerDestination(destination: ConsentDestination): void {
+    this.destinations.set(destination.id, destination);
+    this.reconcileDestination(destination);
+  }
+
+  /** Whether a destination is currently active (loaded and still eligible) — its emit gate. */
+  isDestinationActive(id: string): boolean {
+    return this.active.has(id);
+  }
+
+  /** Subscribe to snapshot changes; returns an unsubscribe function. */
+  subscribe(listener: ConsentListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** The effective decision for one purpose under the current layers. */
+  private effective(purpose: ConsentPurpose): ConsentDecision {
+    if (purpose === ESSENTIAL) return "granted";
+    if (!this.approved.has(purpose)) return "denied"; // tenant never approved it exists
+    return this.directDecisions.get(purpose) ?? this.cmpDecisions.get(purpose) ?? "denied";
+  }
+
+  private compute(): ConsentSnapshot {
+    const eligible = CONSENT_PURPOSES.filter((p) => this.effective(p) === "granted");
+    return makeSnapshot(eligible);
+  }
+
+  private update(): ConsentSnapshot {
+    this.snapshot = this.compute();
+    for (const destination of this.destinations.values()) {
+      this.reconcileDestination(destination);
+    }
+    for (const listener of this.listeners) listener(this.snapshot);
+    return this.snapshot;
+  }
+
+  private reconcileDestination(destination: ConsentDestination): void {
+    const eligibleNow = isPurposeEligible(this.snapshot, destination.purpose);
+    if (eligibleNow && !this.loaded.has(destination.id)) {
+      this.loaded.add(destination.id);
+      this.active.add(destination.id);
+      destination.load(); // once, deferred until first eligible
+    } else if (eligibleNow && !this.active.has(destination.id)) {
+      this.active.add(destination.id);
+      destination.onResume?.(this.snapshot); // eligible again — update, do not re-init
+    } else if (!eligibleNow && this.active.has(destination.id)) {
+      this.active.delete(destination.id);
+      destination.onWithdraw?.(this.snapshot); // stop future events + vendor update
+    }
+  }
+}

package/packages/public-runtime/src/integration/consent-cmp-demand.ts

@@ -0,0 +1,115 @@
+/**
+ * The CMP demand ledger — which Consent Management Platform adapters a merchant may
+ * select is DERIVED from demonstrated demand, never a hardcoded catalog (ADR 0014 P2
+ * `integration-catalog-consent-google-meta`, ADR 0025: "the first CMP adapter is
+ * selected from demonstrated demand").
+ *
+ * There is no built-in list of "supported" CMPs anywhere in this module. An adapter
+ * becomes SELECTABLE only once distinct tenants have demonstrated demand for it and
+ * that demand crosses a threshold; before then every CMP choice fails closed. So the
+ * first CMP Storefront adapts is whichever real demand first proves, not an engineering
+ * guess baked into code.
+ *
+ * Pure and edge-safe: a ledger of signals in, a derived selectable set out. Malformed
+ * signals never count toward demand (they cannot inflate a bogus adapter into being
+ * selectable).
+ */
+
+/** One recorded demand signal: a tenant asked for a named CMP adapter, once. */
+export interface CmpDemandSignal {
+  /** The requested CMP adapter identifier (e.g. an opaque vendor slug). */
+  adapterId: string;
+  /** The tenant that demonstrated the demand — distinct tenants are what count. */
+  tenantPublicId: string;
+  /** ISO-8601 instant the demand was recorded. */
+  at: string;
+  /** Where the demand came from (a merchant request, a support ticket), for the record. */
+  source?: string;
+}
+
+/** The accumulated demand across all tenants. */
+export interface CmpDemandLedger {
+  signals: readonly CmpDemandSignal[];
+}
+
+/**
+ * Distinct tenants that must demonstrate demand before an adapter is offered. A
+ * single request is not "demonstrated demand"; the default requires a real cohort.
+ */
+export const DEFAULT_CMP_DEMAND_THRESHOLD = 3;
+
+/** Per-adapter demand summary for the admin record and the selectable decision. */
+export interface CmpAdapterDemand {
+  adapterId: string;
+  /** How many DISTINCT tenants requested it — the demand measure. */
+  distinctTenants: number;
+  firstRequestedAt: string;
+  lastRequestedAt: string;
+  /** True only when `distinctTenants >= threshold`: the merchant may select it. */
+  selectable: boolean;
+}
+
+/** A signal is well-formed only if it carries a non-empty adapter, tenant, and ISO instant. */
+function isWellFormedSignal(signal: CmpDemandSignal): boolean {
+  return (
+    typeof signal.adapterId === "string" &&
+    signal.adapterId.length > 0 &&
+    typeof signal.tenantPublicId === "string" &&
+    signal.tenantPublicId.length > 0 &&
+    typeof signal.at === "string" &&
+    /\d{4}-\d{2}-\d{2}T/.test(signal.at) &&
+    !Number.isNaN(Date.parse(signal.at))
+  );
+}
+
+/**
+ * Summarize a demand ledger into per-adapter demand, sorted by distinct-tenant demand
+ * (desc), then adapter id. Malformed signals and repeat requests from the same tenant
+ * for the same adapter never inflate the count.
+ */
+export function summarizeCmpDemand(
+  ledger: CmpDemandLedger,
+  threshold: number = DEFAULT_CMP_DEMAND_THRESHOLD,
+): CmpAdapterDemand[] {
+  const byAdapter = new Map<string, { tenants: Set<string>; first: string; last: string }>();
+  for (const signal of ledger.signals) {
+    if (!isWellFormedSignal(signal)) continue;
+    const entry = byAdapter.get(signal.adapterId) ?? {
+      tenants: new Set<string>(),
+      first: signal.at,
+      last: signal.at,
+    };
+    entry.tenants.add(signal.tenantPublicId);
+    if (signal.at < entry.first) entry.first = signal.at;
+    if (signal.at > entry.last) entry.last = signal.at;
+    byAdapter.set(signal.adapterId, entry);
+  }
+  return [...byAdapter.entries()]
+    .map(([adapterId, entry]) => ({
+      adapterId,
+      distinctTenants: entry.tenants.size,
+      firstRequestedAt: entry.first,
+      lastRequestedAt: entry.last,
+      selectable: entry.tenants.size >= threshold,
+    }))
+    .sort((a, b) => b.distinctTenants - a.distinctTenants || a.adapterId.localeCompare(b.adapterId));
+}
+
+/** The adapter ids a merchant may currently select — the demonstrated-demand set. */
+export function demonstratedCmpAdapters(
+  ledger: CmpDemandLedger,
+  threshold: number = DEFAULT_CMP_DEMAND_THRESHOLD,
+): string[] {
+  return summarizeCmpDemand(ledger, threshold)
+    .filter((d) => d.selectable)
+    .map((d) => d.adapterId);
+}
+
+/** Whether one adapter has crossed the demonstrated-demand threshold and is selectable. */
+export function isCmpSelectable(
+  ledger: CmpDemandLedger,
+  adapterId: string,
+  threshold: number = DEFAULT_CMP_DEMAND_THRESHOLD,
+): boolean {
+  return demonstratedCmpAdapters(ledger, threshold).includes(adapterId);
+}