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

package/apps/storefront/src/lib/dev/cockpit/stepper.ts

@@ -0,0 +1,116 @@
+/**
+ * Progressive stepper + staged flow. Drives Run → Edit → What's next with
+ * progressive disclosure: only the current stage shows, completed stages
+ * collapse to a done-bar, and the flow AUTO-ADVANCES on monitor.ts's REAL loop
+ * signal (never a timer) — Step 1 completes when the local server is live,
+ * Step 2 when a real save→reload is observed since the edit step began.
+ * Consumes the shared tot:loop-state event from monitor.ts (one poll for the
+ * whole page). Imported from a processed `<script>` in cockpit.astro (ADR
+ * 0013), rendered only when isLocalDevLoop.
+ *
+ * Progress is persisted in sessionStorage. This is REQUIRED, not a nicety:
+ * saving a watched file triggers Vite's global full-reload, which reloads
+ * THIS /dev tab too — resetting in-memory state and re-baselining the very
+ * save that should advance Edit→Next. Persisting done-flags + current stage +
+ * the edit baseline (the lastSaveAt watermark captured when the edit step
+ * began, BEFORE the qualifying save) lets the flow survive that reload and
+ * credit the save.
+ */
+export function initStepper(): void {
+  const stepper: any = document.getElementById("stepper");
+  if (!stepper) return;
+  const stages: any = { run: document.getElementById("stage-run"), edit: document.getElementById("stage-edit"), next: document.getElementById("stage-next") };
+  const bars: any = { run: document.getElementById("bar-run"), edit: document.getElementById("bar-edit") };
+  const celRun = document.getElementById("cel-run");
+  const celEdit = document.getElementById("cel-edit");
+  const toNext: any = document.getElementById("toNext");
+  const detect = document.getElementById("detect");
+  const detectTxt = document.getElementById("detectTxt");
+  const detectEdit = document.getElementById("detect-edit");
+  const detectEditTxt = document.getElementById("detectEditTxt");
+  const barRunMeta = document.getElementById("bar-run-meta");
+  const barEditMeta = document.getElementById("bar-edit-meta");
+  const toast = document.getElementById("toast");
+  const toastMsg = document.getElementById("toastMsg");
+  let tT: ReturnType<typeof setTimeout>;
+  const reduce = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const SS = window.sessionStorage;
+  function load(k: string, d: any) { try { const v = SS.getItem(k); return v === null ? d : JSON.parse(v); } catch (e) { return d; } }
+  function put(k: string, v: any) { try { SS.setItem(k, JSON.stringify(v)); } catch (e) {} }
+
+  function ping(m: string, once?: string) {
+    if (once && load(once, false)) return;
+    if (once) put(once, true);
+    if (!toast || !toastMsg) return;
+    toastMsg.textContent = m; toast.classList.add("show");
+    clearTimeout(tT); tT = setTimeout(() => { toast.classList.remove("show"); }, 1900);
+  }
+
+  const state = {
+    unlocked: load("tot.unlocked", { run: true, edit: false, next: false }),
+    done: load("tot.done", { run: false, edit: false }),
+    current: load("tot.current", "run"),
+  };
+  let editBase = load("tot.editBase", null);
+  function persist() { put("tot.unlocked", state.unlocked); put("tot.done", state.done); put("tot.current", state.current); }
+
+  function render() {
+    Array.prototype.forEach.call(stepper.querySelectorAll(".snode"), (n: any) => {
+      const s = n.getAttribute("data-go");
+      n.setAttribute("data-st", state.current === s ? "active" : state.done[s] ? "done" : state.unlocked[s] ? "done" : "locked");
+    });
+    Object.keys(stages).forEach((s) => { if (stages[s]) stages[s].hidden = state.current !== s; });
+    if (bars.run) bars.run.hidden = !(state.done.run && state.current !== "run");
+    if (bars.edit) bars.edit.hidden = !(state.done.edit && state.current !== "edit");
+    // Contextual celebrate banners reflect achieved state (survive reloads).
+    if (celRun && state.done.run) celRun.hidden = false;
+    if (celEdit && state.done.edit) celEdit.hidden = false;
+    if (toNext) toNext.disabled = !state.unlocked.next;
+  }
+  function goTo(s: string) {
+    if (!state.unlocked[s]) return;
+    state.current = s; persist(); render();
+    window.scrollTo({ top: 0, behavior: reduce ? "auto" : "smooth" });
+  }
+
+  function onSignal(s: any) {
+    if (!s || s.offline) return;
+
+    // Step 1 — local server is live.
+    if (s.server && !state.done.run) {
+      state.done.run = true; state.unlocked.edit = true;
+      if (editBase === null) { editBase = s.lastSaveAt || 0; put("tot.editBase", editBase); }
+      persist();
+      if (barRunMeta && s.port) barRunMeta.textContent = "localhost:" + s.port + (s.tenant ? "/" + s.tenant + "/" : "/");
+      if (detect) detect.setAttribute("data-listening", "false");
+      if (detectTxt) detectTxt.textContent = "Your store is live on this machine.";
+      if (state.current === "run") { goTo("edit"); } else { render(); }
+      ping("Your store is live", "tot.pinged.run");
+    }
+
+    // Step 2 — a NEW save (since the edit step began) has been reflected by a reload.
+    if (state.done.run && !state.done.edit && editBase !== null) {
+      const newSave = (s.lastSaveAt || 0) > editBase;
+      const reflected = (s.lastSaveAt || 0) > 0 && (s.lastReloadAt || 0) >= (s.lastSaveAt || 0);
+      if (newSave && !reflected && detectEditTxt) {
+        detectEditTxt.textContent = "Change detected — reloading your store…";
+      }
+      if (newSave && reflected) {
+        state.done.edit = true; state.unlocked.next = true; persist();
+        if (barEditMeta && s.watchedFile) barEditMeta.textContent = s.watchedFile;
+        if (detectEdit) detectEdit.setAttribute("data-listening", "false");
+        if (detectEditTxt) detectEditTxt.textContent = "Saved — your store reloaded. That's the loop.";
+        if (state.current === "edit") { goTo("next"); } else { render(); }
+        ping("Saved — your page reloaded", "tot.pinged.edit");
+      }
+    }
+  }
+
+  render();
+  Array.prototype.forEach.call(document.querySelectorAll("[data-go]"), (el: any) => {
+    el.addEventListener("click", () => { goTo(el.getAttribute("data-go")); });
+  });
+  window.addEventListener("tot:loop-state", (e: any) => { onSignal(e.detail); });
+  if (window.__totLoop) onSignal(window.__totLoop);
+}

package/apps/storefront/src/lib/dev/cockpit/themeToggle.ts

@@ -0,0 +1,23 @@
+/**
+ * Theme toggle: flip data-theme on <html>, seeded from the OS preference on
+ * first click, and PERSISTED to localStorage so a reload stays on the manual
+ * choice (the is:inline head seed script reads this same key before first
+ * paint — that one stays is:inline because it must run synchronously before
+ * CSS paints, the one legitimate is:inline case per ADR 0013). Clearing
+ * storage falls back to prefers-color-scheme again, same as a first-ever
+ * visit. Imported from a processed `<script>` in cockpit.astro.
+ */
+export function initThemeToggle(): void {
+  const root = document.documentElement;
+  const btn = document.getElementById("themeBtn");
+  if (!btn) return;
+  const KEY = "tot.theme";
+  function store(v: string) { try { localStorage.setItem(KEY, v); } catch (e) {} }
+  btn.addEventListener("click", () => {
+    const cur = root.getAttribute("data-theme");
+    const next = cur === "dark" ? "light" : cur === "light" ? "dark"
+      : (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "dark");
+    root.setAttribute("data-theme", next);
+    store(next);
+  });
+}

package/apps/storefront/src/lib/dev/runtimeStore.ts

@@ -1,6 +1,6 @@
 /**
  * Per-DEVELOPER "local dev runtime" latest-state — the LIVE half of the
- * local→hosted activity bridge (G1). Where activityStore.ts holds a ring buffer
+ * local→hosted activity bridge. Where activityStore.ts holds a ring buffer
  * of file-SAVE events, this holds the most recent heartbeat a developer's LOCAL
  * `tot dev`/`tot start` sent (see the CLI's dev-heartbeat.mjs). The hosted cockpit
  * reads it to show a LIVE, clickable local-dev link + the running CLI version.

package/apps/storefront/src/lib/edgeCache.ts

@@ -15,10 +15,11 @@
  * response with Set-Cookie, and anything non-200/non-HTML. In `astro dev` there
  * is no `caches` global, so every helper is a clean no-op.
  *
- * Note on the CSP nonce: a stored page carries the nonce it was rendered with, in
- * both its inline tags and its CSP header, and is served to many users. That is
- * safe — the nonce is not a secret; it only has to match within one identical,
- * non-personalized document, which it does.
+ * Note on the CSP nonce (ADR 0018): a stored page is NONCE-FREE — its inline tags
+ * and CSP header carry the nonce placeholder, not a live nonce. A fresh per-response
+ * nonce is stamped in at serve time (stampResponseNonce), on both the cold render and
+ * the warm cache hit, so no cached artifact ever holds a reusable nonce and every
+ * response gets its own matching nonce/CSP pair.
  */
 
 /** Synthetic internal origin for cache keys — never hits the network. */
@@ -62,12 +63,23 @@ export function pageCacheKey(
   pathname: string,
   search: string,
   version: number,
+  planRevision?: string,
 ): Request {
-  return new Request(`${CACHE_ORIGIN}/${tenantId}/v${version}${pathname}${search}`);
+  // A stored page carries the CSP header it was rendered with, INCLUDING any
+  // version-scoped integration origins. Folding the resolved `planRevision` into
+  // the key makes a warm entry plan-scoped: a rollback/uninstall resolves a new
+  // revision, so the old entry is unreachable (a clean miss that re-renders
+  // without the removed origins) instead of surviving to TTL. Absent (no
+  // integration plane resolved) the key is byte-identical to the non-integration
+  // form, so a plain tenant pays nothing and its cache is never busted.
+  const planSegment = planRevision ? `/pr:${planRevision}` : "";
+  return new Request(
+    `${CACHE_ORIGIN}/${tenantId}/v${version}${planSegment}${pathname}${search}`,
+  );
 }
 
 /**
- * Cache key for a digest-addressed static-bundle response (T2, ADR 0012).
+ * Cache key for a digest-addressed static-bundle response (ADR 0012).
  * Keyed by `treeDigest` instead of the integer `cachever` `pageCacheKey` uses —
  * a pointer flip to a NEW digest is a different key, so it is a clean cache
  * miss (never a stale serve of the old digest); an unchanged digest keeps

package/apps/storefront/src/lib/email/candidateConflictEmail.ts

@@ -0,0 +1,80 @@
+/**
+ * The storefront's OWN branded "your open change now conflicts" email. When the shared
+ * preview base advances (another change was accepted/integrated), every OTHER open
+ * candidate is auto-rebased onto the new base; a clean rebuild is silent, but a genuine
+ * same-line overlap can't be auto-combined and needs the author's call. This is the push
+ * notification for that case — the author is pinged the MOMENT their change actually
+ * conflicts with someone else's merge, not at their own accept attempt.
+ *
+ * Rendered here (our brand), transmitted by tot20 (see lib/messaging/messagesClient.ts).
+ * Email HTML rules: inline styles only, table-free simple layout, a visible fallback URL
+ * under the button.
+ */
+
+/** Minimal HTML escape for untrusted interpolation (file paths, store name). */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export interface CandidateConflictEmailInput {
+  /** Display name of the store/experience. Default "Regulated Storefront". */
+  storeName?: string;
+  /** The author's open change PR number, when known. */
+  prNumber?: number | null;
+  /** Repo-relative paths that changed on both sides and need the author's pick. */
+  unresolved: string[];
+  /** Absolute deep-link to the resolve UI (admin#publish), or null when no origin is known. */
+  resolveUrl?: string | null;
+}
+
+const FILE_LIMIT = 12;
+
+export function renderCandidateConflictEmail(input: CandidateConflictEmailInput): {
+  subject: string;
+  html: string;
+} {
+  const store = input.storeName?.trim() || "Regulated Storefront";
+  const label = input.prNumber != null ? `PR #${input.prNumber}` : "your change";
+  const subject = `Action needed: ${label} now conflicts with ${store}`;
+  const url = input.resolveUrl || null;
+
+  const files = input.unresolved.slice(0, FILE_LIMIT);
+  const overflow = input.unresolved.length - files.length;
+  const fileList = files.length
+    ? `<ul style="margin:8px 0 0;padding-left:20px;color:#33415b;font-size:14px;">${files
+        .map((f) => `<li style="margin:2px 0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;">${esc(f)}</li>`)
+        .join("")}${overflow > 0 ? `<li style="margin:2px 0;color:#8593a8;">…and ${overflow} more file(s)</li>` : ""}</ul>`
+    : "";
+
+  const cta = url
+    ? `<div style="margin:28px 0;">
+        <a href="${esc(url)}" style="display:inline-block;background:#0b7a6d;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:999px;">Resolve it now</a>
+      </div>
+      <p style="margin:0 0 4px;font-size:13px;color:#55637a;">Or paste this link into your browser:</p>
+      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${esc(url)}" style="color:#0b7a6d;">${esc(url)}</a></p>`
+    : "";
+
+  const html = `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
+  <body style="margin:0;padding:0;background:#f7f9fc;">
+    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#33415b;">
+      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0b7a6d;margin:0 0 24px;">
+        Token of Trust&#169; &middot; ${esc(store)}
+      </div>
+      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.02em;margin:0 0 12px;color:#0a2540;">${esc(label)} needs your input</h1>
+      <p style="margin:0 0 8px;color:#33415b;">The store moved on — another change was just accepted into <strong>${esc(store)}</strong>, and we tried to rebuild ${esc(label)} on top of it automatically. Most of it merged cleanly, but these files were edited on both sides and need you to pick which version wins:</p>
+      ${fileList}
+      ${cta}
+      <p style="margin:16px 0 0;font-size:14px;color:#33415b;">You can also resolve it from the command line — <code style="font-family:ui-monospace,SFMono-Regular,Menlo,monospace;">tot preview --strategy=ours</code> keeps your version, <code style="font-family:ui-monospace,SFMono-Regular,Menlo,monospace;">tot preview --strategy=theirs</code> takes the store's.</p>
+      <p style="margin:24px 0 0;font-size:12px;color:#8593a8;border-top:1px solid #e3e8ef;padding-top:16px;">Your change is safe and still open — it just stays not-mergeable until you resolve these files. Nothing was overwritten.</p>
+    </div>
+  </body>
+</html>`;
+
+  return { subject, html };
+}

package/apps/storefront/src/lib/integration/browserEnvironment.ts

@@ -0,0 +1,137 @@
+/**
+ * Storefront-side resolution of the renderer-owned four-stage browser
+ * environment (`@tot/public-runtime` `resolveBrowserEnvironment`). This is the ONE
+ * place request state is turned into the authoritative environment object; both
+ * document mounts (Layout.astro and `rawHtmlResponse`) serialize the result, so
+ * the object is identical in both by construction.
+ *
+ * The stage is derived from server facts only — `import.meta.env.DEV`, the request
+ * host, the resolved customization environment, and whether this is a per-change
+ * candidate render — never a client-supplied value. A candidate render is always
+ * `candidate` and never `live`; anything unresolved stays non-live.
+ */
+import {
+  resolveBrowserEnvironment,
+  resolveEnvironmentOnlyPlan,
+  type BrowserEnvironment,
+  type EffectivePlan,
+  type IntegrationSiteSurface,
+} from "@tot/public-runtime";
+import { isAdminPath } from "@/lib/auth/loginGate";
+
+/**
+ * The non-secret render revision: the commit SHA this build was cut from (baked at
+ * build time, the same value GET /health reports), or `"local"` when there is no
+ * git context (dev, vitest). Never a token or signed URL.
+ */
+function platformRevision(): string {
+  return typeof __GIT_SHA__ !== "undefined" && __GIT_SHA__ ? __GIT_SHA__ : "local";
+}
+
+/** A request host is local when it is served on loopback (`astro dev` or a local built Worker). */
+function isLocalHost(host: string): boolean {
+  return host.startsWith("localhost") || host.startsWith("127.0.0.1");
+}
+
+/**
+ * Map the resolved tenant + request path to a document surface. Admin/cockpit
+ * paths are `admin`; cart/checkout paths are `checkout`; a catalog tenant is
+ * `storefront`; a marketing tenant (no catalog) is `marketing`.
+ */
+export function deriveSiteSurface(input: {
+  catalog: boolean;
+  pathname: string;
+}): IntegrationSiteSurface {
+  // Admin + the cockpit control-plane panel (host-routed `/cockpit` or tenant-first
+  // `/<tenant>/cockpit`) are the `admin` surface.
+  if (isAdminPath(input.pathname) || /^\/(?:[^/]+\/)?cockpit(?:\/|$)/.test(input.pathname)) {
+    return "admin";
+  }
+  if (/^\/(checkout|cart)(\/|$)/.test(input.pathname)) return "checkout";
+  return input.catalog ? "storefront" : "marketing";
+}
+
+/**
+ * The normal (non-candidate) per-request environment object, computed once by the
+ * middleware. `astro dev` and a Worker served on localhost both resolve to `local`
+ * (their CSP-enforcement mode differs — report-only vs enforced — but that is a
+ * response-header concern, not part of this object).
+ */
+export function requestBrowserEnvironment(input: {
+  host: string;
+  isPreviewHost: boolean;
+  customizationEnv: "live" | "test";
+  canonicalHost: string;
+  siteSurface: IntegrationSiteSurface;
+}): BrowserEnvironment {
+  return resolveBrowserEnvironment({
+    dev: import.meta.env.DEV,
+    localHost: isLocalHost(input.host),
+    candidate: false,
+    previewHost: input.isPreviewHost,
+    customizationEnv: input.customizationEnv,
+    siteSurface: input.siteSurface,
+    canonicalHost: input.canonicalHost,
+    revision: platformRevision(),
+  });
+}
+
+/**
+ * CSP enforcement mode for this runtime — the axis that stays DISTINCT from the
+ * `local` stage. `astro dev` (Node) serves un-nonced Vite `<style>`/`<script>`, so a
+ * strict nonce policy would blank the site: it is REPORT-ONLY there (violations
+ * still surface). The built Worker is CSP-clean, so the strict policy is ENFORCED —
+ * including the built Worker run locally, which is how enforced CSP is proven.
+ * Report-only-dev and enforced-built-Worker are both correct; only the mode differs,
+ * never the four-stage environment object.
+ */
+export type CspEnforcementMode = "report-only" | "enforced";
+
+export function cspEnforcementMode(dev: boolean): CspEnforcementMode {
+  return dev ? "report-only" : "enforced";
+}
+
+/** The response header name that carries the mode: report-only in dev, enforced otherwise. */
+export function cspHeaderName(
+  dev: boolean,
+): "Content-Security-Policy-Report-Only" | "Content-Security-Policy" {
+  return dev ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy";
+}
+
+/**
+ * The environment object for a per-change candidate render (the cockpit candidate
+ * renderer, the revision renderer, and the not-yet-built PR page). The stage is
+ * always `candidate` — never `live`, even when the underlying tenant is live — and
+ * `revision` is the candidate's own version identity (a versionId / head sha), a
+ * public, non-secret value.
+ */
+export function candidateBrowserEnvironment(input: {
+  canonicalHost: string;
+  revision: string;
+  siteSurface?: IntegrationSiteSurface;
+}): BrowserEnvironment {
+  return resolveBrowserEnvironment({
+    dev: import.meta.env.DEV,
+    localHost: false,
+    candidate: true,
+    previewHost: true,
+    customizationEnv: "test",
+    siteSurface: input.siteSurface ?? "marketing",
+    canonicalHost: input.canonicalHost,
+    revision: input.revision,
+  });
+}
+
+/**
+ * The resolved effective plan for a candidate render — the `candidate`-stage
+ * environment wrapped in an environment-only plan so `rawHtmlResponse` (the raw
+ * mount of the fixed-phase engine) renders the same renderer-owned phases a live
+ * page gets. No integration declarations are materialized on the candidate hot
+ * path, so this is environment-only until that wiring lands.
+ */
+export function candidateIntegrationPlan(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+): EffectivePlan {
+  return resolveEnvironmentOnlyPlan(candidateBrowserEnvironment(input), tenantPublicId);
+}

package/apps/storefront/src/lib/integration/managedInstallDeclarations.ts

@@ -0,0 +1,72 @@
+/**
+ * Materialize active managed-analytics installs into the render plane's existing
+ * declaration seam. `app_installs` owns status/manifest and MAX(seq) owns the
+ * active public config; candidates and drafts are never read here.
+ */
+import {
+  ENVIRONMENT_SCHEMA_VERSION,
+  buildPlatformAdapterDeclaration,
+  validateIntegrationManifest,
+  type IntegrationDeclarationInput,
+} from "@tot/public-runtime";
+import { AppVersionStore } from "../apps/appVersionStore.js";
+import type { Queryable } from "../d1/catalog.js";
+
+const MANAGED_KIND = "managed-analytics-v1";
+
+interface ActiveManagedRow {
+  install_id: string;
+  app_id: string;
+  app_version: string;
+  manifest: string;
+}
+
+/**
+ * Return only declarations whose canonical row, current immutable activation,
+ * and reviewed platform-adapter rebuild agree. Malformed/stale rows fail closed
+ * individually; an unavailable database is handled by the caller as no effects.
+ */
+export async function loadActiveManagedInstallDeclarations(
+  db: Queryable,
+  tenantPublicId: string,
+): Promise<IntegrationDeclarationInput[]> {
+  const rows = await db.all<ActiveManagedRow>(
+    `SELECT install_id, app_id, app_version, manifest
+       FROM app_installs
+      WHERE tenant_id = ? AND managed_kind = ? AND status = 'active'
+      ORDER BY install_id`,
+    tenantPublicId,
+    MANAGED_KIND,
+  );
+  const versions = new AppVersionStore(db);
+  const declarations: IntegrationDeclarationInput[] = [];
+  for (const row of rows) {
+    try {
+      const manifest = validateIntegrationManifest(JSON.parse(row.manifest) as unknown);
+      const current = await versions.currentVersion(row.install_id);
+      if (!manifest.ok || !current || current.tenantId !== tenantPublicId) continue;
+      if (current.appVersion !== row.app_version || current.facets.appVersion !== row.app_version) continue;
+      if (current.facets.digest !== manifest.value.app.digest || manifest.value.app.id !== row.app_id) continue;
+      const destinationId = current.facets.publicConfig["destinationId"];
+      if (typeof destinationId !== "string") continue;
+      const built = buildPlatformAdapterDeclaration({
+        adapterId: row.app_id,
+        ids: { live: destinationId },
+        tenantPublicId,
+        environment: {
+          schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+          siteSurface: "storefront",
+          environment: "live",
+          canonicalHost: tenantPublicId,
+          revision: `managed-live:${current.seq}`,
+        },
+      });
+      if (!built.ok || built.declaration.manifest.app.digest !== manifest.value.app.digest) continue;
+      declarations.push({ ...built.declaration, ref: `managed-install:${row.install_id}` });
+    } catch {
+      // Persisted JSON/version corruption must disable this install, never widen
+      // CSP or partially materialize a subscription.
+    }
+  }
+  return declarations;
+}

package/apps/storefront/src/lib/integration/nonceStamp.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-response CSP-nonce stamping (ADR 0018 nonce non-serialization; ext-kernel-04).
+ *
+ * The renderer emits a nonce-free template: every platform inline tag and the CSP
+ * header carry {@link INTEGRATION_NONCE_PLACEHOLDER}, never a live nonce. This is
+ * what the edge cache stores — a nonce-free artifact. At serve time (a cold render
+ * OR a warm cache hit) this stamps ONE fresh per-response nonce into both the HTML
+ * body and the CSP header, so every response gets a fresh, matching nonce/CSP pair
+ * and no nonce is ever reused across responses.
+ */
+import { INTEGRATION_NONCE_PLACEHOLDER, stampNonce } from "@tot/public-runtime";
+
+const CSP_HEADERS = [
+  "content-security-policy",
+  "content-security-policy-report-only",
+] as const;
+
+/** A fresh, non-guessable per-response nonce. */
+export function freshNonce(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Replace the nonce placeholder with a fresh `nonce` in a response's CSP header(s)
+ * and — for an HTML response — its body. Non-HTML responses keep their (streamed)
+ * body untouched; their CSP header is still stamped. A response with no placeholder
+ * (a static-bundle body, an API JSON) is returned effectively unchanged.
+ */
+export async function stampResponseNonce(
+  response: Response,
+  nonce: string,
+): Promise<Response> {
+  for (const header of CSP_HEADERS) {
+    const value = response.headers.get(header);
+    if (value && value.includes(INTEGRATION_NONCE_PLACEHOLDER)) {
+      response.headers.set(header, stampNonce(value, nonce));
+    }
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/html")) return response;
+
+  const body = await response.text();
+  return new Response(stampNonce(body, nonce), {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}

package/apps/storefront/src/lib/integration/tenantDeclarations.ts

@@ -0,0 +1,116 @@
+/**
+ * Tenant-local integration declaration materialization (ext-kernel-09).
+ *
+ * This is the ONE production seam that turns a tenant's OWN declared, exact-version
+ * integrations into the already-materialized {@link IntegrationDeclarationInput} set
+ * the render hot path consumes. The interim marketing bridge
+ * ({@link resolveInterimBridgePlan}) resolves that set into the effective plan the
+ * fixed-phase engine serves — refusing a regulated tenant, resolving an eligible
+ * unregulated one — so a declared tenant boots its integration on-by-default
+ * (consent-gated) with no page edit and no vendor branch.
+ *
+ * A tenant with no declaration returns the empty set, so the bridge resolves an
+ * environment-only plan and the request is byte-identical to non-integration
+ * behavior (zero cost). The declarations are already materialized in tenant config
+ * (the manifest, the resolved public config, the set of asset paths present for the
+ * version); this loader only reads them, fail-closed — resolution is the bridge's
+ * job, materialization is config's, and the two never blur.
+ */
+import type { IntegrationDeclarationInput, IntegrationManifest, TenantConfig } from "@tot/public-runtime";
+
+const NO_DECLARATIONS: readonly IntegrationDeclarationInput[] = Object.freeze([]);
+
+/**
+ * Read a tenant's already-materialized tenant-local declarations. Returns the empty
+ * set (never throws) when the tenant declares none or the field is malformed — an
+ * undeclared tenant must resolve to the environment-only plan, never an error.
+ */
+export function loadTenantIntegrationDeclarations(
+  tenant: Pick<TenantConfig, "integrations">,
+): readonly IntegrationDeclarationInput[] {
+  const declared = tenant.integrations;
+  if (!Array.isArray(declared) || declared.length === 0) return NO_DECLARATIONS;
+  return declared;
+}
+
+// ---------------------------------------------------------------------------
+// Demo tenant-local declaration — a same-origin sandbox analytics adapter.
+//
+// Seeded on the unregulated marketing demo/home tenants so a preview deploy
+// DEMONSTRABLY materializes a real integration on-by-default: its exact-version
+// entry module (committed under `public/apps/…`, so always materialized and served
+// same-origin) flows the declaration → interim bridge → effective plan → boot
+// descriptor → lifecycle import. Loading is consent-gated (purpose `analytics`,
+// held back under the default-deny snapshot until granted), and the declared
+// beacon origin reaches the strict CSP via `cspNeeds`. A regulated tenant carrying
+// the same declaration is still REFUSED by the bridge.
+// ---------------------------------------------------------------------------
+
+/** The demo adapter's app id — a same-origin, sandbox-tier marketing analytics adapter. */
+export const DEMO_ANALYTICS_APP_ID = "tot.demo.analytics";
+/** The demo adapter's exact pinned version. */
+export const DEMO_ANALYTICS_VERSION = "0.1.0";
+/**
+ * The same-origin, exact-version entry module the lifecycle runtime dynamically
+ * imports. Committed under `apps/storefront/public/apps/…` so it is served verbatim
+ * at this root-absolute URL and is ALWAYS materialized (no R2 pointer needed).
+ */
+export const DEMO_ANALYTICS_ENTRY_URL = `/apps/${DEMO_ANALYTICS_APP_ID}/${DEMO_ANALYTICS_VERSION}/entry.js`;
+/** The beacon endpoint the demo declaration reserves in CSP (`connect-src`). */
+export const DEMO_ANALYTICS_BEACON_ORIGIN = "https://demo-analytics.tokenoftrust.com";
+
+/** The demo adapter's shared browser manifest (ext-kernel-01 v2). */
+const DEMO_ANALYTICS_MANIFEST: IntegrationManifest = {
+  schemaVersion: 2,
+  app: {
+    id: DEMO_ANALYTICS_APP_ID,
+    name: "ToT Demo Analytics",
+    version: DEMO_ANALYTICS_VERSION,
+    digest: `sha256:${DEMO_ANALYTICS_APP_ID}-${DEMO_ANALYTICS_VERSION}`,
+    publisher: "Token of Trust",
+  },
+  compatibility: { storefrontBrowserContract: ">=2.0.0 <3.0.0", configurationSchemaVersion: 1 },
+  browser: {
+    executionTier: "sandbox",
+    entry: { asset: DEMO_ANALYTICS_ENTRY_URL, format: "module", phase: "document.deferred" },
+    contributions: [],
+    dependencies: [],
+    publicConfigSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["siteId"],
+      properties: { siteId: { type: "string" } },
+    },
+    consent: {
+      purposes: ["analytics"],
+      loadWhen: "all-declared-purposes-eligible",
+      unknownState: "block",
+    },
+    // Same-origin entry loads under the strict base `'self'`; the declared beacon
+    // origin is the advanced exact source the compiler folds into `connect-src`.
+    csp: { profiles: [], sources: { "connect-src": [DEMO_ANALYTICS_BEACON_ORIGIN] } },
+    permissions: { events: ["storefront.page.viewed.v1"], data: [], actions: [], domIntent: "none" },
+    performanceBudget: {
+      maxTransferredBytes: 20000,
+      maxAdditionalRequests: 1,
+      maxMainThreadMilliseconds: 20,
+      mustBeAsyncOrDeferred: true,
+    },
+  },
+  server: { topics: [], secretRequirements: [] },
+  assurance: { requestedClassification: "baseline", regulatedTenantDefault: "disabled-until-certified" },
+  configurationMigrations: [],
+};
+
+/**
+ * The demo tenant-local declaration seeded on the unregulated marketing demo tenants.
+ * `materializedAssets` names the committed same-origin entry module, so the resolver's
+ * fail-closed materialized-asset check passes without any R2/publish step.
+ */
+export const DEMO_ANALYTICS_DECLARATION: IntegrationDeclarationInput = {
+  origin: "tenant-local",
+  ref: "config/tenants:demo-analytics",
+  manifest: DEMO_ANALYTICS_MANIFEST,
+  publicConfig: { siteId: "tot-demo" },
+  materializedAssets: [DEMO_ANALYTICS_ENTRY_URL],
+};

package/apps/storefront/src/lib/membership/eligibility.ts

@@ -1,6 +1,6 @@
 /**
  * Shopper membership eligibility — the request-scoped seam that resolves whether
- * the current shopper is a member, and which tier (F10).
+ * the current shopper is a member, and which tier.
  *
  * Phase 1 storefronts have NO shopper-login/account source (member accounts are
  * a Phase-2 managed-checkout capability), so this resolves anonymous