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

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

@@ -0,0 +1,260 @@
+/**
+ * The merchant consent configuration — the tenant-approval surface that FEEDS the
+ * neutral consent broker (ext-policy-03 `consent-broker.ts`). A merchant declares which
+ * consent purposes exist, each one's legal basis and default state, and (optionally) a
+ * CMP adapter; this module validates that declaration FAIL-CLOSED and materializes it
+ * into the {@link TenantConsentPolicy} the broker is constructed from, plus the
+ * default-state seed the broker starts at.
+ *
+ * The broker is the single source of truth for what a shopper is eligible for at
+ * runtime; this is where a tenant's decisions about that broker are made, validated,
+ * and turned into broker inputs. Nothing here grants anything at runtime — it only
+ * approves which purposes may EVER become eligible and what their pre-interaction
+ * default is.
+ *
+ * Fail-closed contract (each clause is a release gate):
+ *   - An unknown/unlisted purpose is rejected — an invalid purpose mapping blocks.
+ *   - `essential` is implicit and platform-owned; a config may not redeclare it.
+ *   - A `consent` legal-basis purpose may NOT default to granted — a shopper must
+ *     opt in; only `legitimate-interest` may default granted (opt-out).
+ *   - A CMP adapter may be selected only from DEMONSTRATED demand
+ *     (`consent-cmp-demand.ts`); with no demand evidence every CMP choice is rejected.
+ */
+import {
+  CONSENT_PURPOSES,
+  type ConsentPurpose,
+} from "../integration-capabilities.js";
+import { CONSENT_CONFIG_SCHEMA_VERSION } from "./version.js";
+import {
+  ConsentBroker,
+  type ConsentDecision,
+  type ConsentLegalBasis,
+  type TenantConsentPolicy,
+} from "./consent-broker.js";
+import {
+  Violations,
+  reqObject,
+  reqEnum,
+  reqLiteral,
+  reqArray,
+  optString,
+  rejectUnknownKeys,
+  isPlainObject,
+  type ContractResult,
+} from "./result.js";
+import {
+  DEFAULT_CMP_DEMAND_THRESHOLD,
+  isCmpSelectable,
+  type CmpDemandLedger,
+} from "./consent-cmp-demand.js";
+
+/** `essential` is always on and platform-owned; it is never a merchant-configurable purpose. */
+const ESSENTIAL: ConsentPurpose = "essential";
+
+const LEGAL_BASES: readonly ConsentLegalBasis[] = ["consent", "legitimate-interest"];
+const DECISIONS: readonly ConsentDecision[] = ["granted", "denied"];
+
+/** One merchant-configured purpose: whether it exists, its basis, and its default state. */
+export interface ConsentPurposeConfig {
+  purpose: ConsentPurpose;
+  legalBasis: ConsentLegalBasis;
+  /** What a fresh shopper sees before any CMP/banner interaction. */
+  defaultState: ConsentDecision;
+}
+
+/** The merchant's CMP choice. `none` uses the native banner only; `cmp` names an adapter. */
+export type ConsentCmpChoice =
+  | { mode: "none" }
+  | { mode: "cmp"; adapterId: string };
+
+/** The whole tenant consent configuration — a closed, versioned record. */
+export interface TenantConsentConfig {
+  schemaVersion: typeof CONSENT_CONFIG_SCHEMA_VERSION;
+  purposes: readonly ConsentPurposeConfig[];
+  cmp: ConsentCmpChoice;
+}
+
+/** Options that decide whether a CMP choice is admissible. */
+export interface ConsentConfigValidationOptions {
+  /** The demand ledger a CMP choice is checked against — no ledger means no CMP is selectable. */
+  demand?: CmpDemandLedger;
+  /** Distinct-tenant demand a CMP must have demonstrated to be selectable. */
+  cmpDemandThreshold?: number;
+}
+
+const PURPOSE_KEYS = ["purpose", "legalBasis", "defaultState"];
+const CONFIG_KEYS = ["schemaVersion", "purposes", "cmp"];
+const CMP_KEYS = ["mode", "adapterId"];
+
+/**
+ * Validate a raw consent configuration fail-closed. Any unknown field, unknown purpose,
+ * a redeclared `essential`, a `consent`-basis purpose that defaults to granted, a
+ * duplicate purpose, or a CMP adapter without demonstrated demand yields structured
+ * violations and NO config — a caller can never persist or publish an invalid mapping.
+ */
+export function validateConsentConfig(
+  raw: unknown,
+  options: ConsentConfigValidationOptions = {},
+): ContractResult<TenantConsentConfig> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectUnknownKeys(root, CONFIG_KEYS, v, "");
+
+  reqLiteral(root, "schemaVersion", CONSENT_CONFIG_SCHEMA_VERSION, v, "");
+
+  const purposes = validatePurposes(root, v);
+  const cmp = validateCmp(root, v, options);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return {
+    ok: true,
+    value: {
+      schemaVersion: CONSENT_CONFIG_SCHEMA_VERSION,
+      purposes: purposes!,
+      cmp: cmp!,
+    },
+  };
+}
+
+function validatePurposes(
+  root: Record<string, unknown>,
+  v: Violations,
+): ConsentPurposeConfig[] | undefined {
+  const arr = reqArray(root, "purposes", v, "");
+  if (!arr) return undefined;
+  const out: ConsentPurposeConfig[] = [];
+  const seen = new Set<ConsentPurpose>();
+
+  arr.forEach((entry, i) => {
+    const path = `purposes[${i}]`;
+    if (!isPlainObject(entry)) {
+      v.add(path, "type", "Expected a purpose object.");
+      return;
+    }
+    rejectUnknownKeys(entry, PURPOSE_KEYS, v, path);
+
+    const purpose = reqEnum<ConsentPurpose>(entry, "purpose", CONSENT_PURPOSES, v, path);
+    const legalBasis = reqEnum<ConsentLegalBasis>(entry, "legalBasis", LEGAL_BASES, v, path);
+    const defaultState = reqEnum<ConsentDecision>(entry, "defaultState", DECISIONS, v, path);
+    if (!purpose || !legalBasis || !defaultState) return;
+
+    if (purpose === ESSENTIAL) {
+      // `essential` is always granted and platform-owned; it is never a merchant decision.
+      v.add(`${path}.purpose`, "essential_is_implicit", "`essential` is always on and cannot be configured.");
+      return;
+    }
+    if (seen.has(purpose)) {
+      v.add(`${path}.purpose`, "duplicate", `Duplicate purpose "${purpose}"; duplicates are rejected.`);
+      return;
+    }
+    seen.add(purpose);
+
+    if (legalBasis === "consent" && defaultState === "granted") {
+      // A consent-basis purpose must default to denied — a shopper opts in, never pre-granted.
+      v.add(
+        `${path}.defaultState`,
+        "consent_default_grant_forbidden",
+        `Purpose "${purpose}" has legal basis "consent"; its default state must be "denied" (opt-in), not "granted".`,
+      );
+      return;
+    }
+
+    out.push({ purpose, legalBasis, defaultState });
+  });
+
+  return out;
+}
+
+function validateCmp(
+  root: Record<string, unknown>,
+  v: Violations,
+  options: ConsentConfigValidationOptions,
+): ConsentCmpChoice | undefined {
+  const cmp = reqObject(root["cmp"], v, "cmp");
+  if (!cmp) return undefined;
+  rejectUnknownKeys(cmp, CMP_KEYS, v, "cmp");
+  const mode = reqEnum<"none" | "cmp">(cmp, "mode", ["none", "cmp"], v, "cmp");
+  if (!mode) return undefined;
+
+  if (mode === "none") return { mode: "none" };
+
+  const adapterId = optString(cmp, "adapterId", v, "cmp");
+  if (!adapterId) {
+    v.add("cmp.adapterId", "type", 'A CMP choice ("cmp") requires a non-empty "adapterId".');
+    return undefined;
+  }
+  const ledger = options.demand ?? { signals: [] };
+  const threshold = options.cmpDemandThreshold ?? DEFAULT_CMP_DEMAND_THRESHOLD;
+  if (!isCmpSelectable(ledger, adapterId, threshold)) {
+    v.add(
+      "cmp.adapterId",
+      "cmp_no_demand",
+      `CMP adapter "${adapterId}" has not demonstrated the demand required to be selectable; a CMP is chosen from demonstrated demand, not a hardcoded list.`,
+    );
+    return undefined;
+  }
+  return { mode: "cmp", adapterId };
+}
+
+/**
+ * Project a validated config onto the {@link TenantConsentPolicy} the broker is
+ * constructed from: every configured purpose with its legal basis. `essential` is left
+ * implicit (the broker adds it). This is the tenant-approval half of what feeds the broker.
+ */
+export function toTenantConsentPolicy(config: TenantConsentConfig): TenantConsentPolicy {
+  return {
+    purposes: config.purposes.map((p) => ({ purpose: p.purpose, legalBasis: p.legalBasis })),
+  };
+}
+
+/**
+ * The default-state seed applied to a fresh broker — the decisions a shopper starts at
+ * before any interaction. Only purposes configured to default `granted` (which the
+ * validator restricts to `legitimate-interest`) contribute; `consent`-basis purposes
+ * contribute nothing and stay denied until an affirmative decision grants them.
+ */
+export function defaultDecisionSeed(
+  config: TenantConsentConfig,
+): Partial<Record<ConsentPurpose, ConsentDecision>> {
+  const seed: Partial<Record<ConsentPurpose, ConsentDecision>> = {};
+  for (const p of config.purposes) {
+    if (p.defaultState === "granted") seed[p.purpose] = "granted";
+  }
+  return seed;
+}
+
+/**
+ * Build the neutral consent broker a validated config describes: constructed from the
+ * tenant policy and advanced to the configured default state. This is the concrete seam
+ * by which a merchant's consent configuration feeds the ext-policy-03 broker — the same
+ * broker instance the browser loader and server destination filter then read.
+ */
+export function buildTenantConsentBroker(config: TenantConsentConfig): ConsentBroker {
+  const broker = new ConsentBroker(toTenantConsentPolicy(config));
+  const seed = defaultDecisionSeed(config);
+  if (Object.keys(seed).length > 0) broker.setDecisions(seed);
+  return broker;
+}
+
+/**
+ * The purposes a destination requires that the tenant has NOT approved to exist — the
+ * unmet consent dependencies the admin surface displays before publish. `essential` is
+ * always satisfied; an unknown purpose is treated as unmet (fail closed).
+ */
+export function unmetConsentDependencies(
+  config: TenantConsentConfig,
+  required: readonly ConsentPurpose[],
+): ConsentPurpose[] {
+  const approved = new Set<ConsentPurpose>([ESSENTIAL, ...config.purposes.map((p) => p.purpose)]);
+  const unmet: ConsentPurpose[] = [];
+  for (const purpose of required) {
+    if (!approved.has(purpose) && !unmet.includes(purpose)) unmet.push(purpose);
+  }
+  return unmet;
+}
+
+/** An empty, valid configuration: no purpose approved beyond the implicit essential floor, no CMP. */
+export function emptyConsentConfig(): TenantConsentConfig {
+  return { schemaVersion: CONSENT_CONFIG_SCHEMA_VERSION, purposes: [], cmp: { mode: "none" } };
+}

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

@@ -0,0 +1,125 @@
+/**
+ * Consent preview — proves the exact defaults and updates a shopper would see under a
+ * given merchant consent configuration, by driving the real ext-policy-03 broker
+ * (`consent-broker.ts`) the config feeds. Preview is not a mock: it constructs the same
+ * broker `buildTenantConsentBroker` produces, then replays a sequence of shopper/CMP
+ * updates, recording the resulting eligibility at each step.
+ *
+ * Two acceptance guarantees fall out of running the real broker:
+ *   - The FIRST step is what a fresh shopper sees before interacting — the configured
+ *     defaults, demonstrably.
+ *   - A `cmp-removed` step can only NARROW eligibility versus the step before it —
+ *     disabling a CMP never grants a purpose. {@link cmpDisableNarrows} is the witness;
+ *     preview records it per removal step, and a broadening removal is an invariant
+ *     violation surfaced on the step.
+ *
+ * Pure and edge-safe: config + actions in, snapshots out. No I/O, no wall clock.
+ */
+import type { ConsentPurpose } from "../integration-capabilities.js";
+import type {
+  CmpConsentReport,
+  ConsentDecision,
+  ConsentSnapshot,
+} from "./consent-broker.js";
+import { buildTenantConsentBroker, type TenantConsentConfig } from "./consent-config.js";
+
+/** A shopper/CMP interaction to replay against the previewed broker. */
+export type ConsentPreviewAction =
+  | { kind: "cmp"; label?: string; report: CmpConsentReport }
+  | { kind: "cmp-removed"; label?: string }
+  | { kind: "banner"; label?: string; decisions: Partial<Record<ConsentPurpose, ConsentDecision>> };
+
+/** One preview step: the eligibility a shopper would see after an action. */
+export interface ConsentPreviewStep {
+  label: string;
+  action: ConsentPreviewAction["kind"] | "default";
+  eligiblePurposes: ConsentPurpose[];
+  snapshotId: string;
+  /**
+   * For a `cmp-removed` step: whether eligibility only narrowed versus the prior step
+   * (always true from a correct broker). `false` is an invariant violation — a CMP
+   * removal that granted a purpose.
+   */
+  narrowedOnly?: boolean;
+}
+
+export interface ConsentPreviewResult {
+  /** What a fresh shopper sees before any interaction — the configured defaults. */
+  defaultStep: ConsentPreviewStep;
+  /** Each replayed update, in order — the updates a shopper would see. */
+  steps: ConsentPreviewStep[];
+  /** True when no `cmp-removed` step broadened eligibility (a CMP disable never granted). */
+  cmpDisableSafe: boolean;
+}
+
+/** True when `after` grants no purpose `before` did not — i.e. eligibility only narrowed or held. */
+export function cmpDisableNarrows(before: ConsentSnapshot, after: ConsentSnapshot): boolean {
+  return after.eligiblePurposes.every((p) => before.eligiblePurposes.includes(p));
+}
+
+function stepFrom(
+  label: string,
+  action: ConsentPreviewStep["action"],
+  snapshot: ConsentSnapshot,
+): ConsentPreviewStep {
+  return {
+    label,
+    action,
+    eligiblePurposes: [...snapshot.eligiblePurposes],
+    snapshotId: snapshot.snapshotId,
+  };
+}
+
+/**
+ * Replay a merchant consent configuration through the real broker and return the
+ * default a shopper sees plus each subsequent update. The default step reflects the
+ * configured default state; each action step reflects what the same shopper would then
+ * see. A CMP removal is annotated with whether it only narrowed eligibility.
+ */
+export function previewConsentConfig(
+  config: TenantConsentConfig,
+  actions: readonly ConsentPreviewAction[] = [],
+): ConsentPreviewResult {
+  const broker = buildTenantConsentBroker(config);
+  const defaultStep = stepFrom("Default (fresh shopper)", "default", broker.getSnapshot());
+
+  const steps: ConsentPreviewStep[] = [];
+  let previous = broker.getSnapshot();
+  let cmpDisableSafe = true;
+
+  for (const action of actions) {
+    let snapshot: ConsentSnapshot;
+    switch (action.kind) {
+      case "cmp":
+        snapshot = broker.applyCmp(action.report);
+        break;
+      case "cmp-removed":
+        snapshot = broker.applyCmp(null);
+        break;
+      case "banner":
+        snapshot = broker.setDecisions(action.decisions);
+        break;
+    }
+    const step = stepFrom(action.label ?? defaultLabel(action.kind), action.kind, snapshot);
+    if (action.kind === "cmp-removed") {
+      const narrowed = cmpDisableNarrows(previous, snapshot);
+      step.narrowedOnly = narrowed;
+      if (!narrowed) cmpDisableSafe = false;
+    }
+    steps.push(step);
+    previous = snapshot;
+  }
+
+  return { defaultStep, steps, cmpDisableSafe };
+}
+
+function defaultLabel(kind: ConsentPreviewAction["kind"]): string {
+  switch (kind) {
+    case "cmp":
+      return "CMP consent applied";
+    case "cmp-removed":
+      return "CMP removed";
+    case "banner":
+      return "Shopper banner choice";
+  }
+}