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

package/apps/storefront/src/lib/compliance/tamper-sentinel-boot.ts

@@ -0,0 +1,152 @@
+/**
+ * Client bootstrap that arms the protected-surface tamper sentinel on the live
+ * storefront. It maps the storefront's existing protected-surface DOM (compliance
+ * notices, the age-gate host, cart/checkout controls) to the policy-04
+ * `PROTECTED_SURFACES` markers the sentinel keys on, wires the browser recovery
+ * sinks (a durable `sendBeacon` to the server receiver + an operator console
+ * alert), and starts observing.
+ *
+ * This is a DETECTIVE control, mounted unconditionally — it never prevents a
+ * mutation, it recovers from one. It is defensive by construction: absent globals,
+ * a server (non-browser) context, or a missing surface each degrade to a no-op
+ * rather than throwing on the page.
+ */
+import {
+  createTamperSentinel,
+  PROTECTED_SURFACE_ATTR,
+  type TamperSink,
+} from "./tamper-sentinel";
+import type {
+  ProtectedSurface,
+  TamperAttribution,
+  TamperEvidenceBeacon,
+  IntegrationEnvironment,
+  IntegrationSiteSurface,
+} from "@tot/public-runtime";
+import { INTEGRATION_PLAN_GLOBAL } from "@tot/public-runtime";
+
+/** Where the browser posts a tamper beacon; the server receiver records + suspends. */
+export const TAMPER_BEACON_ENDPOINT = "/api/compliance/tamper";
+
+/**
+ * Existing storefront DOM conventions per protected surface. The sentinel keys on
+ * `data-tot-protected-surface`; this bridges the surfaces already rendered by the
+ * compliance components + commerce chrome onto that single marker, so no component
+ * has to be re-plumbed to be guarded.
+ */
+const SURFACE_SELECTORS: Record<ProtectedSurface, readonly string[]> = {
+  "age-gate": ["[data-tot-compliance]", '[data-compliance="age-gate"]'],
+  "compliance-warning": [
+    '[data-compliance="nicotine-warning"]',
+    '[data-compliance="prop65"]',
+    '[data-compliance="pact-act"]',
+    '[data-compliance="purchase-limit"]',
+    '[data-compliance="adult-signature"]',
+  ],
+  "shipping-jurisdiction-notice": [
+    '[data-compliance="shipping-restriction"]',
+    '[data-compliance="jurisdiction"]',
+  ],
+  "cart-preflight": ["[data-cart-preflight]"],
+  "checkout-controls": ["[data-checkout-controls]"],
+};
+
+/** Stamp the sentinel marker onto every element matching a known protected-surface selector. */
+export function stampProtectedSurfaces(doc: Document): void {
+  for (const surface of Object.keys(SURFACE_SELECTORS) as ProtectedSurface[]) {
+    for (const selector of SURFACE_SELECTORS[surface]) {
+      for (const el of Array.from(doc.querySelectorAll(selector))) {
+        if (!el.hasAttribute(PROTECTED_SURFACE_ATTR)) {
+          el.setAttribute(PROTECTED_SURFACE_ATTR, surface);
+        }
+      }
+    }
+  }
+}
+
+interface BootPlan {
+  environment?: string;
+  tenantPublicId?: string;
+  integrations?: Array<{ origin?: string; appId?: string; version?: string }>;
+}
+
+function readPlan(win: Window): BootPlan | null {
+  const raw = (win as unknown as Record<string, unknown>)[INTEGRATION_PLAN_GLOBAL];
+  return raw && typeof raw === "object" ? (raw as BootPlan) : null;
+}
+
+function integrationsFrom(plan: BootPlan): TamperAttribution[] {
+  const out: TamperAttribution[] = [];
+  for (const i of plan.integrations ?? []) {
+    if (i.appId && i.version && i.origin) {
+      out.push({ appId: i.appId, version: i.version, origin: i.origin });
+    }
+  }
+  return out;
+}
+
+function beaconSink(win: Window): TamperSink {
+  const post = (beacon: TamperEvidenceBeacon): void => {
+    try {
+      const body = JSON.stringify(beacon);
+      const nav = win.navigator as Navigator & {
+        sendBeacon?: (url: string, data?: BodyInit) => boolean;
+      };
+      if (typeof nav.sendBeacon === "function") {
+        nav.sendBeacon(TAMPER_BEACON_ENDPOINT, new Blob([body], { type: "application/json" }));
+        return;
+      }
+      void fetch(TAMPER_BEACON_ENDPOINT, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true,
+      }).catch(() => {});
+    } catch {
+      /* recovery already happened in the DOM; a failed beacon must never throw */
+    }
+  };
+  return {
+    emitEvidence: post,
+    alert: (beacon) => {
+      // Operator-visible, secret-free line. The durable record is the posted beacon.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[tamper] detective recovery: surface=${beacon.surface} kind=${beacon.kind} recovered=${beacon.recovered} app=${beacon.attribution?.appId ?? "unattributable"}`,
+      );
+    },
+    // The server receiver resolves + executes the suspend from the posted beacon;
+    // the browser cannot suspend an install itself.
+    suspend: () => {},
+  };
+}
+
+/**
+ * Arm the sentinel for this page. No-ops (returns `null`) outside a browser or when
+ * no integration plan is present (nothing third-party can have tampered).
+ */
+export function bootTamperSentinel(win: Window = globalThis as unknown as Window) {
+  if (typeof win === "undefined" || typeof win.document === "undefined") return null;
+  const plan = readPlan(win);
+  if (!plan || !plan.tenantPublicId || !plan.environment) return null;
+
+  const doc = win.document;
+  stampProtectedSurfaces(doc);
+
+  const siteSurface =
+    (doc.documentElement?.getAttribute("data-tot-site-surface") as IntegrationSiteSurface | null) ??
+    "storefront";
+
+  const sentinel = createTamperSentinel({
+    document: doc,
+    context: {
+      tenant: plan.tenantPublicId,
+      environment: plan.environment as IntegrationEnvironment,
+      siteSurface,
+      integrations: integrationsFrom(plan),
+    },
+    sink: beaconSink(win),
+  });
+  sentinel.arm();
+  return sentinel;
+}

package/apps/storefront/src/lib/compliance/tamper-sentinel.ts

@@ -0,0 +1,327 @@
+/**
+ * Protected-surface tamper sentinel — a DETECTIVE runtime control (D-R7,
+ * `integration-protected-tamper-recovery`).
+ *
+ * Full-parent third-party code shares the document with the storefront, so its DOM
+ * reach cannot be enforceably narrowed (WS2 security model). This sentinel does NOT
+ * prevent mutation and never claims to. It DETECTS mutation of the platform-owned
+ * protected surfaces (policy-04 `PROTECTED_SURFACES` — age gates, nicotine/Prop 65
+ * warnings, shipping/jurisdiction notices, cart preflight, checkout controls),
+ * RESTORES the safe state it captured at arm time, EMITS a durable evidence beacon,
+ * ALERTS operations, and — when the mutation is attributable to a single
+ * integration — requests that integration be SUSPENDED.
+ *
+ * Surfaces are keyed by the `data-tot-protected-surface="<surface>"` marker whose
+ * value is one of `PROTECTED_SURFACES`. Each marked element captured at
+ * {@link createTamperSentinel} `arm()` becomes the AUTHORITATIVE node: the sentinel
+ * holds its identity, its pristine subtree, and its position, and reconciles the
+ * live DOM back to that baseline on every sweep. Because it restores the SAME node
+ * object it captured, a clone-replace that strips event listeners is recovered by
+ * reinstating the original (listener-bearing) node.
+ *
+ * Recovery is idempotent: rapid re-mutation just re-triggers a sweep that restores
+ * again. The sentinel disconnects its own observer while restoring and drains the
+ * records it caused, so its repair never feeds back as a new detection.
+ */
+import {
+  buildTamperEvidenceBeacon,
+  attributeSoleSuspect,
+  PROTECTED_SURFACES,
+  type ProtectedSurface,
+  type TamperKind,
+  type TamperAttribution,
+  type TamperEvidenceBeacon,
+  type IntegrationEnvironment,
+  type IntegrationSiteSurface,
+} from "@tot/public-runtime";
+
+/** The DOM marker a protected surface stamps; its value is a `ProtectedSurface`. */
+export const PROTECTED_SURFACE_ATTR = "data-tot-protected-surface";
+
+/** The marker an integration's own injected node carries, enabling positive attribution. */
+export const INTEGRATION_MARKER_ATTR = "data-tot-app";
+
+const PROTECTED_SURFACE_SET: ReadonlySet<string> = new Set(PROTECTED_SURFACES);
+
+/** The recovery actions a sentinel drives, injected so the engine stays pure/testable. */
+export interface TamperSink {
+  /** Persist the durable evidence beacon (e.g. `navigator.sendBeacon` to the server). */
+  emitEvidence(beacon: TamperEvidenceBeacon): void;
+  /** Raise an operational alert for the detected+recovered tamper. */
+  alert(beacon: TamperEvidenceBeacon): void;
+  /** Suspend the attributable integration. Only called when attribution is resolved. */
+  suspend(attribution: TamperAttribution, beacon: TamperEvidenceBeacon): void;
+}
+
+/** The tenant/environment scope + active integrations a sentinel stamps onto every beacon. */
+export interface TamperSentinelContext {
+  tenant: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+  /** The non-platform integrations active on the page, used for attribution. */
+  integrations: readonly TamperAttribution[];
+  /** ISO-clock seam for deterministic tests. */
+  now?: () => string;
+}
+
+export interface TamperSentinelOptions {
+  document: Document;
+  context: TamperSentinelContext;
+  sink: TamperSink;
+}
+
+export interface TamperSentinel {
+  /** Capture the pristine baseline of every marked surface and start observing. */
+  arm(): void;
+  /** Stop observing. Baselines are retained; `sweep()` still works. */
+  disarm(): void;
+  /** Reconcile every guarded surface back to baseline once, synchronously. */
+  sweep(): void;
+  /** The number of surfaces currently guarded (surfaces present at `arm()`). */
+  readonly guardCount: number;
+}
+
+interface Guard {
+  surface: ProtectedSurface;
+  /** The authoritative captured node; its identity is preserved across recovery. */
+  node: Element;
+  parent: Node | null;
+  /** The sibling the node sat before, so it is reinserted at its exact position. */
+  anchor: ChildNode | null;
+  baselineInnerRaw: string;
+  baselineInner: string;
+  baselineText: string;
+  baselineOverlayCount: number;
+}
+
+function normWhitespace(html: string): string {
+  return html.replace(/>\s+</g, "><").replace(/\s+/g, " ").trim();
+}
+
+function normText(text: string | null): string {
+  return (text ?? "").replace(/\s+/g, " ").trim();
+}
+
+/** A descendant styled to cover the surface (inline positioned + a stacking/inset hint). */
+function isCoveringElement(el: Element): boolean {
+  const style = el.getAttribute("style");
+  if (!style) return false;
+  const s = style.toLowerCase();
+  const positioned = /position\s*:\s*(absolute|fixed)/.test(s);
+  const stacks = /z-index\s*:/.test(s) || /inset\s*:/.test(s) || /top\s*:/.test(s);
+  return positioned && stacks;
+}
+
+function coveringCount(el: Element): number {
+  let n = 0;
+  for (const child of Array.from(el.querySelectorAll("*"))) {
+    if (isCoveringElement(child)) n++;
+  }
+  return n;
+}
+
+function isHidden(el: Element): boolean {
+  if (el.hasAttribute("hidden")) return true;
+  if (el.getAttribute("aria-hidden") === "true") return true;
+  const anyEl = el as unknown as { style?: CSSStyleDeclaration };
+  const style = anyEl.style;
+  if (style) {
+    if (style.display === "none") return true;
+    if (style.visibility === "hidden") return true;
+    if (style.opacity === "0") return true;
+  }
+  return false;
+}
+
+function unhide(el: Element): void {
+  el.removeAttribute("hidden");
+  if (el.getAttribute("aria-hidden") === "true") el.removeAttribute("aria-hidden");
+  const anyEl = el as unknown as { style?: CSSStyleDeclaration };
+  const style = anyEl.style;
+  if (style) {
+    style.removeProperty("display");
+    style.removeProperty("visibility");
+    style.removeProperty("opacity");
+  }
+}
+
+export function createTamperSentinel(options: TamperSentinelOptions): TamperSentinel {
+  const { document, context, sink } = options;
+  const doc = document;
+  const guards: Guard[] = [];
+  let observer: MutationObserver | null = null;
+  // Re-entrancy guard: our own restoration mutates the DOM, which the observer
+  // would re-deliver. The guard makes a sweep atomic so recovery never feeds back
+  // into an unbounded observe→restore→observe storm.
+  let sweeping = false;
+
+  const now = (): string => context.now?.() ?? new Date().toISOString();
+
+  function captureGuards(): void {
+    guards.length = 0;
+    for (const el of Array.from(doc.querySelectorAll(`[${PROTECTED_SURFACE_ATTR}]`))) {
+      const surface = el.getAttribute(PROTECTED_SURFACE_ATTR) ?? "";
+      if (!PROTECTED_SURFACE_SET.has(surface)) continue;
+      guards.push({
+        surface: surface as ProtectedSurface,
+        node: el,
+        parent: el.parentNode,
+        anchor: el.nextSibling,
+        baselineInnerRaw: el.innerHTML,
+        baselineInner: normWhitespace(el.innerHTML),
+        baselineText: normText(el.textContent),
+        baselineOverlayCount: coveringCount(el),
+      });
+    }
+  }
+
+  function siblingImpostor(g: Guard): Element | null {
+    for (const el of Array.from(doc.querySelectorAll(`[${PROTECTED_SURFACE_ATTR}="${g.surface}"]`))) {
+      if (el !== g.node && el.isConnected) return el;
+    }
+    return null;
+  }
+
+  function inspect(g: Guard): TamperKind | null {
+    if (!g.node.isConnected) {
+      const impostor = siblingImpostor(g);
+      if (impostor) {
+        const sameMarkup =
+          normWhitespace(impostor.innerHTML) === g.baselineInner &&
+          normText(impostor.textContent) === g.baselineText;
+        return sameMarkup ? "listener-stripped" : "displaced";
+      }
+      return "removed";
+    }
+    if (isHidden(g.node)) return "hidden";
+    if (coveringCount(g.node) > g.baselineOverlayCount) return "overlaid";
+    if (normText(g.node.textContent) !== g.baselineText) return "text-altered";
+    if (normWhitespace(g.node.innerHTML) !== g.baselineInner) return "subtree-mutated";
+    return null;
+  }
+
+  /** Read a positively-identifying integration appId from the tampering node, if any. */
+  function injectedAppId(g: Guard, kind: TamperKind): string | null {
+    if (kind === "removed" || kind === "displaced" || kind === "listener-stripped") {
+      const impostor = siblingImpostor(g);
+      const id = impostor?.getAttribute(INTEGRATION_MARKER_ATTR);
+      if (id) return id;
+    }
+    if (g.node.isConnected) {
+      for (const child of Array.from(g.node.querySelectorAll(`[${INTEGRATION_MARKER_ATTR}]`))) {
+        const id = child.getAttribute(INTEGRATION_MARKER_ATTR);
+        if (id) return id;
+      }
+    }
+    return null;
+  }
+
+  function resolveAttribution(appId: string | null): TamperAttribution | null {
+    if (appId) {
+      const match = context.integrations.find((i) => i.appId === appId);
+      if (match) return match;
+    }
+    return attributeSoleSuspect(context.integrations);
+  }
+
+  function removeImpostors(g: Guard): void {
+    for (const el of Array.from(doc.querySelectorAll(`[${PROTECTED_SURFACE_ATTR}="${g.surface}"]`))) {
+      if (el !== g.node && el.isConnected) el.remove();
+    }
+  }
+
+  function reinsert(g: Guard): void {
+    if (g.node.isConnected) return;
+    if (g.parent && (g.parent as Node & { isConnected: boolean }).isConnected) {
+      if (g.anchor && g.anchor.parentNode === g.parent) {
+        g.parent.insertBefore(g.node, g.anchor);
+      } else {
+        g.parent.appendChild(g.node);
+      }
+      return;
+    }
+    doc.body?.appendChild(g.node);
+  }
+
+  function restore(g: Guard): void {
+    removeImpostors(g);
+    reinsert(g);
+    unhide(g.node);
+    if (normWhitespace(g.node.innerHTML) !== g.baselineInner) {
+      // `baselineInnerRaw` is the platform's OWN pristine subtree, snapshotted at
+      // arm() before any third-party code executes — restoring it is exactly the
+      // safe-state recovery this control exists for, not injection of external HTML.
+      g.node.innerHTML = g.baselineInnerRaw;
+    }
+  }
+
+  function reportAndRecover(g: Guard): void {
+    const kind = inspect(g);
+    if (!kind) return;
+    const appId = injectedAppId(g, kind);
+    restore(g);
+    const recovered = inspect(g) === null;
+    const attribution = resolveAttribution(appId);
+    const beacon = buildTamperEvidenceBeacon({
+      tenant: context.tenant,
+      environment: context.environment,
+      siteSurface: context.siteSurface,
+      surface: g.surface,
+      kind,
+      detectedAt: now(),
+      recovered,
+      attribution,
+    });
+    sink.emitEvidence(beacon);
+    sink.alert(beacon);
+    if (attribution) sink.suspend(attribution, beacon);
+  }
+
+  function sweep(): void {
+    if (sweeping) return;
+    sweeping = true;
+    observer?.disconnect();
+    try {
+      for (const g of guards) reportAndRecover(g);
+    } finally {
+      // Drain the mutations our own recovery caused so they aren't re-detected.
+      observer?.takeRecords?.();
+      startObserving();
+      sweeping = false;
+    }
+  }
+
+  function startObserving(): void {
+    if (!observer) return;
+    const root = doc.documentElement ?? doc.body;
+    if (!root) return;
+    observer.observe(root, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true,
+    });
+  }
+
+  function arm(): void {
+    captureGuards();
+    if (typeof MutationObserver !== "undefined") {
+      observer = new MutationObserver(() => sweep());
+      startObserving();
+    }
+  }
+
+  function disarm(): void {
+    observer?.disconnect();
+    observer = null;
+  }
+
+  return {
+    arm,
+    disarm,
+    sweep,
+    get guardCount() {
+      return guards.length;
+    },
+  };
+}

package/apps/storefront/src/lib/content/index.ts

@@ -1,11 +1,11 @@
 /**
- * Structured content contracts (spec §F4) — ONE import surface for the
+ * Structured content contracts — ONE import surface for the
  * data-driven framework widgets, so tenant content (JSON) and the .astro
  * components share a single typed vocabulary and a tenant never copies HTML/CSS.
  *
- * New F4 contracts: rich text, callouts, needs-review, prose/policy sections,
- * trust strip. Re-exported here alongside the tier/comparison contracts F10
- * already owns (in lib/membership/model) so a membership page and a policy page
+ * New contracts: rich text, callouts, needs-review, prose/policy sections,
+ * trust strip. Re-exported here alongside the tier/comparison contracts already
+ * defined in lib/membership/model, so a membership page and a policy page
  * import from the same place. (The <BrandGrid> `Brand` contract lives with its
  * component in components/commerce/BrandGrid.astro.)
  */
@@ -15,7 +15,7 @@ export * from "./needsReview.js";
 export * from "./prose.js";
 export * from "./trustStrip.js";
 
-// Reused tier contracts (F10) — surfaced here so all structured widgets share
+// Reused tier contracts — surfaced here so all structured widgets share
 // one contract entry point.
 export type {
   Tier,

package/apps/storefront/src/lib/content-edit/applyDiff.ts

@@ -2,7 +2,7 @@
  * Apply a unified diff to a source string — the missing half of the content_edit wire
  * contract. tot-mcp's `content_edit` returns per-file unified DIFFS (`--- a/…` /
  * `+++ b/…` / `@@` hunks), not updated contents; to materialize a draft artifact
- * (decision `draft-overlay-same-origin`) the storefront must re-apply the diff to the
+ * the storefront must re-apply the diff to the
  * exact content it sent.
  *
  * STRICT + FAIL-CLOSED by design: every hunk's context and deletion lines must match

package/apps/storefront/src/lib/content-edit/route.ts

@@ -1,5 +1,5 @@
 /**
- * Route helper for `/api/content-edit/ai-edit` — mirrors `@/lib/change/route.ts`'s
+ * Route helper for `/api/content-edit/ai-edit` — mirrors `@/lib/change/route/route.ts`'s
  * `getChangeClient`: build the env-configured client, or a 503 Response when
  * the MCP integration isn't configured (missing `MCP_BASE_URL`/credentials).
  */

package/apps/storefront/src/lib/d1/catalog.ts

@@ -27,6 +27,13 @@ export interface Queryable {
   first<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | null>;
   run(sql: string, ...params: unknown[]): Promise<void>;
   exec(sql: string): Promise<void>;
+  /** D1 executes a batch sequentially inside one implicit transaction. */
+  batch?(statements: readonly QueryStatement[]): Promise<void>;
+}
+
+export interface QueryStatement {
+  sql: string;
+  params?: readonly unknown[];
 }
 
 /** The slice of the Cloudflare D1Database we use (kept local to avoid a types dep). */
@@ -39,6 +46,7 @@ export interface D1Like {
     };
   };
   exec(sql: string): Promise<unknown>;
+  batch?(statements: unknown[]): Promise<unknown[]>;
 }
 
 /** Adapt a Cloudflare D1Database to the Queryable seam. */
@@ -54,6 +62,10 @@ export function fromD1(db: D1Like): Queryable {
     exec: async (sql: string) => {
       await db.exec(sql);
     },
+    batch: async (statements) => {
+      if (!db.batch) throw new Error("D1 batch is unavailable");
+      await db.batch(statements.map(({ sql, params = [] }) => db.prepare(sql).bind(...params)));
+    },
   };
 }