@tokenoftrust/storefront-runner 0.1.0

package/LICENSE

@@ -0,0 +1,58 @@
+Token of Trust Source-Available License — Local Development Only
+Version 1.0
+
+Copyright (c) 2026 Token of Trust, Inc. All rights reserved.
+
+1. DEFINITIONS
+   "Software" means this source code and any accompanying files in this
+   repository or distribution, including the storefront renderer runtime, the
+   `@tot/public-runtime` package, the storefront-runner distributable, and any
+   derivative works.
+   "Local Development" means running, building, and modifying the Software on a
+   machine you control, for the sole purpose of evaluating it or developing and
+   previewing your own tenant content against it. Serving the Software to any
+   third party, or over any public or shared network, is NOT Local Development.
+   "Token of Trust" means Token of Trust, Inc.
+
+2. GRANT (LOCAL DEVELOPMENT ONLY)
+   Subject to the terms below, Token of Trust grants you a personal,
+   non-exclusive, non-transferable, revocable license to use, copy, build, and
+   modify the Software SOLELY for Local Development.
+
+3. PERMISSION REQUIRED FOR EVERYTHING ELSE
+   Any use of the Software beyond Local Development requires the PRIOR WRITTEN
+   PERMISSION of Token of Trust. Without such permission you may NOT, in whole or
+   in part:
+   (a) deploy, host, serve, or otherwise run the Software in production or for
+       any third party, or on any public, staging, or shared/network-accessible
+       environment;
+   (b) use the Software for any commercial purpose or to provide a service to
+       others;
+   (c) distribute, publish, sublicense, sell, rent, lease, or otherwise make the
+       Software (or a derivative of it) available to any third party; or
+   (d) remove or obscure this license or the copyright notices.
+   To request permission, contact Token of Trust at legal@tokenoftrust.com.
+
+4. NO TRADEMARK LICENSE
+   This license grants no rights to the Token of Trust name, logos, or
+   trademarks.
+
+5. RESERVATION OF RIGHTS
+   All rights not expressly granted are reserved by Token of Trust. This is a
+   source-available license, not an open-source license; the Software is not
+   licensed under any OSI-approved license.
+
+6. TERMINATION
+   This license terminates automatically if you breach it. On termination you
+   must stop using the Software and destroy all copies in your possession.
+
+7. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL TOKEN OF TRUST BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# Storefront Runner
+
+A world-shareable, multi-tenant **renderer runtime** for the Token of Trust
+storefront. It serves N tenants (or differently-named variants of one tenant) at
+path-prefix URLs — the same thing `astro dev` does for the full platform — with
+the control-plane services (content authoring, compliance, and the publish/deploy
+control plane) kept private and **physically carved out**.
+
+## Run
+
+```sh
+pnpm install
+pnpm dev            # astro dev on http://localhost:4321
+```
+
+Tenants resolve by `Host` header first, then by a `/<domain>/…` path prefix
+(DNS-free, for localhost). Try:
+
+- http://localhost:4321/tokenoftrust.com/
+- http://localhost:4321/tokenoftrust-preview.com/   (renamed variant of the same tenant)
+- http://localhost:4321/bigdvapor.net/
+
+## Add a tenant
+
+Adding a tenant — or a renamed variant of an existing one — is a one-object edit
+in `apps/storefront/src/config/tenants.ts` (see `TOKENOFTRUST_PREVIEW_TENANT`),
+plus a `tenants/<id>/` directory for its content/theme/public assets.
+
+## IP boundary
+
+This distributable depends only on `@tot/public-runtime` (the renderer-safe
+model). The private control-plane package is absent, so a control-plane import
+cannot resolve here.
+
+## License
+
+Source-available, **local-development only** (see `LICENSE`). You may run, build,
+and modify this for Local Development. Any other use — deploying, hosting, or
+serving it to third parties, or any production/commercial use — requires the
+prior written permission of Token of Trust, Inc.

package/apps/storefront/.dev.vars.example

@@ -0,0 +1,41 @@
+# Copy to `.dev.vars` for local dev (gitignored). With NO values set, the app
+# falls back to FixtureToTClient reading packages/migration/out/catalog/*.json,
+# so the site renders fully offline. Set the TOT_* block to hit live tot20.
+
+# --- ToT catalog API (leave blank to use fixtures) ---------------------------
+# TOT_CATALOG_BASE_URL=https://api.tokenoftrust.com/api/catalog
+# Either a bearer token...
+# TOT_ACCESS_TOKEN=
+# ...or an API key/secret pair:
+# TOT_API_KEY=
+# TOT_SECRET_KEY=
+
+# --- Storyblok (leave blank to use local fallback content) -------------------
+# Per-tenant delivery token; with none, LocalContentProvider reads
+# src/content/pilot/*.json. The pilot tenant's token also lives in
+# src/config/tenants.ts (placeholder there).
+# STORYBLOK_DELIVERY_TOKEN=
+
+# --- Analytics ---------------------------------------------------------------
+# PUBLIC_CF_ANALYTICS_TOKEN=
+
+# --- Staff broker assertion (#8453 staff-invite-proof-via-broker) ------------
+# The storefront-signed RS256 staff proof presented to tot20 in the
+# X-ToT-Broker-Assertion header (proves the signed-in ToT-staff actor server-side;
+# replaces the spoofable plaintext staff-email field). Server-side ONLY — the
+# private key must NEVER reach the client bundle. With this UNSET, the staff
+# invite / vendor-search / enter-vendor routes fail closed (503).
+#   STOREFRONT_BROKER_PRIVATE_KEY_B64 = base64 of the PKCS8 PEM RS256 private key.
+#   tot20 verifies with the matching PUBLIC key registered under STOREFRONT_BROKER_KID.
+# STOREFRONT_BROKER_PRIVATE_KEY_B64=
+# STOREFRONT_BROKER_KID=storefront-qa-1
+# STOREFRONT_BROKER_ISSUER=storefront
+
+# --- Local dev auth (localhost only; never reaches prod) ----------------------
+# tot20 sends invite/sign-in emails, so on localhost no email goes out. Set
+# DEV_AUTH=1 to instead PRINT the one-time sign-in code to the SERVER CONSOLE
+# (POST /api/auth/send) so you can complete sign-in locally without email. The
+# whole path is behind `import.meta.env.DEV` and is tree-shaken from prod builds.
+# (Accepting the printed code to mint a local session is being wired next — see
+# handoff 2026-07-09-storefront-local-dev-auth-mode.md.)
+# DEV_AUTH=1

package/apps/storefront/.env.example

@@ -0,0 +1,24 @@
+# Storefront environment variables (copy to .env for local dev).
+# All are OPTIONAL — with none set, the storefront runs fully offline:
+# catalog from the local fixture store, content from src/content/<tenant>/*.json.
+
+# --- Catalog backend (ToT) ---------------------------------------------------
+# When BASE_URL + (ACCESS_TOKEN | API_KEY+SECRET_KEY) are set, the storefront
+# reads the live ToT catalog API instead of the local fixtures.
+TOT_CATALOG_BASE_URL=
+TOT_API_KEY=
+TOT_SECRET_KEY=
+TOT_ACCESS_TOKEN=
+
+# --- Storyblok (editorial CMS) -----------------------------------------------
+# Set a real delivery token to switch the pilot tenant from LocalContentProvider
+# to the live StoryblokContentProvider. Model your space's components to match
+# src/lib/storyblok/content-model.ts (home, chrome, pages/*).
+STORYBLOK_PILOT_TOKEN=
+# Space region: eu (default) | us | ap | ca
+STORYBLOK_REGION=eu
+# Content version: published (default) | draft  (use draft for previewing)
+STORYBLOK_VERSION=published
+
+# --- Analytics ---------------------------------------------------------------
+PUBLIC_CF_ANALYTICS_TOKEN=

package/apps/storefront/astro.config.mjs

@@ -0,0 +1,245 @@
+// @ts-check
+import { defineConfig } from "astro/config";
+import cloudflare from "@astrojs/cloudflare";
+import preact from "@astrojs/preact";
+import tailwindcss from "@tailwindcss/vite";
+import { fileURLToPath } from "node:url";
+
+// Repo-root tenants/ dir (colocated tenant layout) + the generated static dest
+// the predev copy step mirrors public/ into. astro.config.mjs lives at
+// apps/storefront/, so tenants/ is two levels up. Forward-slash normalized to
+// match Vite's ctx.file (Vite always reports posix-style paths).
+const TENANTS_DIR = fileURLToPath(new URL("../../tenants", import.meta.url)).replace(/\\/g, "/");
+const PUBLIC_TENANTS_DEST = fileURLToPath(new URL("./public/tenants", import.meta.url));
+
+// Dev-only default posture: save a colocated tenant file → the browser reloads.
+// The `tenants/<id>/` tree sits ABOVE the Astro root and reaches the app only
+// through a lazy `?raw` glob (HTML, bypassed by the dev disk-read) or the predev
+// public/ copy — never Vite's own module graph — so Vite doesn't watch it and a
+// save would otherwise do nothing. We watch it explicitly and reload on change:
+//   - content/**.html — read fresh from disk per request
+//     (LocalContentProvider.readRawDevFile), so just reload. (The Vite HMR client
+//     is injected into these otherwise-pipeline-bypassing pages in dev; see
+//     rawHtmlResponse in src/lib/rawMarketingHtml.ts.)
+//   - public/**        — re-mirror the one changed asset into public/tenants/<id>/
+//     (skipping R2-versioned tenants, like copy-tenant-assets.mjs), then reload.
+// content/*.json, themes/*.json and theme.json are ordinary glob imports, so Vite
+// already invalidates + reloads them — left to default handling. Returning []
+// suppresses the pointless glob HMR that would otherwise fire for the raw files.
+function tenantHotReload() {
+  // Typed `any`: `vite` isn't a direct dependency of this package (it's pulled in
+  // transitively via astro), so `import('vite').Plugin` can't be resolved here and
+  // importing from "vite" would even fail at runtime. `any` keeps the hook params
+  // untyped without that reference.
+  /** @type {any} */
+  const plugin = {
+    name: "tot:tenant-hot-reload",
+    apply: "serve",
+    /** @param {any} server */
+    configureServer(server) {
+      server.watcher.add(TENANTS_DIR);
+    },
+    /** @param {any} ctx */
+    async handleHotUpdate(ctx) {
+      const file = ctx.file.replace(/\\/g, "/");
+      if (!file.startsWith(TENANTS_DIR + "/")) return undefined;
+      const rel = file.slice(TENANTS_DIR.length + 1); // "<id>/<...>"
+      const slash = rel.indexOf("/");
+      if (slash < 0) return undefined;
+      const id = rel.slice(0, slash);
+      const rest = rel.slice(slash + 1);
+
+      // Content HTML: the change invalidates the SSR module graph, so the
+      // Cloudflare Vite plugin reloads the worker and — once it is ready — emits
+      // its own correctly-timed full-reload (which the injected Vite HMR client
+      // acts on). We must NOT send our own reload: firing on the raw file-change
+      // event races ahead of the worker reload, so the browser re-navigates while
+      // miniflare is mid-teardown → "page not loaded" + an error overlay. Just let
+      // default handling run.
+      if (rest.startsWith("content/") && rest.endsWith(".html")) {
+        return undefined;
+      }
+
+      // Public assets (CSS, images) aren't in the module graph — they're mirrored
+      // into public/tenants/<id>/ at predev, and a programmatic write there does
+      // NOT trip the platform's own reload. So: re-mirror the one changed file
+      // (await it so the served copy is current), THEN send the reload ourselves.
+      // Unlike content HTML this reloads no worker, so there's no teardown race to
+      // fire ahead of. Skip R2-versioned tenants, like copy-tenant-assets.mjs.
+      if (rest.startsWith("public/")) {
+        // fs via dynamic import so a config-load issue could never break startup.
+        const [{ cp, mkdir }, { existsSync }, { dirname, join }] = await Promise.all([
+          import("node:fs/promises"),
+          import("node:fs"),
+          import("node:path"),
+        ]);
+        const versioned = existsSync(join(TENANTS_DIR, id, ".tot", "assets-versioned"));
+        if (!versioned) {
+          const target = join(PUBLIC_TENANTS_DEST, id, rest.slice("public/".length));
+          try {
+            await mkdir(dirname(target), { recursive: true });
+            await cp(ctx.file, target);
+          } catch {
+            /* best-effort; still reload below */
+          }
+        }
+        ctx.server.ws.send({ type: "full-reload" });
+        return [];
+      }
+
+      return undefined;
+    },
+  };
+  return plugin;
+}
+
+// Repo root, two levels up (astro.config.mjs lives at apps/storefront/).
+const REPO_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const WIDGET_CLIENT_PATH = fileURLToPath(
+  new URL("./src/lib/dev/ai-widget-client.js", import.meta.url),
+);
+
+/** @param {any} req */
+async function readJsonBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const raw = Buffer.concat(chunks).toString("utf8");
+  return raw ? JSON.parse(raw) : {};
+}
+
+/** @param {any} res @param {number} status @param {any} body */
+function sendJson(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+
+/** @param {unknown} e */
+function errorMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// The inline-AI edit loop (WS5 G1): the floating "✦ ask" box + its dev-server
+// endpoints. Dev-only (`apply: "serve"`) — never runs in `astro build`, so it
+// can never reach the production Cloudflare Worker. The widget itself is
+// unconditional in dev (matching the Vite HMR client injection in
+// rawMarketingHtml.ts) — it's the /__tot/ai-* ENDPOINTS below that gate on
+// TOT_DEV_TENANT (set by scripts/tot-dev.mjs), since that's a Node-process env
+// var these Vite-layer handlers see reliably (unlike SSR code, which under the
+// Cloudflare adapter runs inside workerd and does NOT see it — see tot-dev.mjs's
+// own note on this exact env-var-doesn't-reach-workerd gap). A bare `astro dev`
+// (no active tenant) still shows the widget, but "Ask" reports `no_tenant`
+// rather than erroring silently.
+function inlineAiEditPlugin() {
+  /** @type {any} */
+  const plugin = {
+    name: "tot:inline-ai-edit",
+    apply: "serve",
+    /** @param {any} server */
+    configureServer(server) {
+      server.middlewares.use(async (
+        /** @type {any} */ req,
+        /** @type {any} */ res,
+        /** @type {any} */ next,
+      ) => {
+        if (req.url === "/__tot/ai-widget-client.js") {
+          const { readFileSync } = await import("node:fs");
+          res.setHeader("content-type", "text/javascript");
+          res.end(readFileSync(WIDGET_CLIENT_PATH, "utf8"));
+          return;
+        }
+        if (req.method === "POST" && req.url === "/__tot/ai-edit") {
+          const tenantId = process.env.TOT_DEV_TENANT;
+          if (!tenantId) {
+            sendJson(res, 200, { ok: false, status: "no_tenant", message: "This `astro dev` wasn't started via `tot dev` — no active tenant." });
+            return;
+          }
+          const { handleAiEdit } = await import("../../scripts/dev/ai-edit.mjs");
+          try {
+            const { prompt } = await readJsonBody(req);
+            const result = await handleAiEdit({
+              repoRoot: REPO_ROOT, tenantId, prompt, mcpBaseUrl: undefined,
+            });
+            sendJson(res, 200, result);
+          } catch (e) {
+            sendJson(res, 200, { ok: false, status: "error", message: errorMessage(e) });
+          }
+          return;
+        }
+        if (req.method === "POST" && req.url === "/__tot/ai-undo") {
+          const tenantId = process.env.TOT_DEV_TENANT;
+          if (!tenantId) {
+            sendJson(res, 200, { ok: false, status: "no_tenant", message: "This `astro dev` wasn't started via `tot dev` — no active tenant." });
+            return;
+          }
+          const { handleAiUndo } = await import("../../scripts/dev/ai-edit.mjs");
+          try {
+            sendJson(res, 200, handleAiUndo({ repoRoot: REPO_ROOT, tenantId }));
+          } catch (e) {
+            sendJson(res, 200, { ok: false, status: "error", message: errorMessage(e) });
+          }
+          return;
+        }
+        next();
+      });
+    },
+    // Covers pages that DO go through Astro/Vite's own render pipeline (e.g.
+    // Layout.astro commerce pages). Raw marketing pages (content/home.html)
+    // bypass that pipeline entirely — they inject the same script tag
+    // themselves in rawMarketingHtml.ts, right next to the Vite HMR client
+    // that function already injects for the same reason.
+    /** @param {string} html */
+    transformIndexHtml(html) {
+      const tag = '<script type="module" src="/__tot/ai-widget-client.js"></script>';
+      return html.includes("</body>") ? html.replace("</body>", `${tag}</body>`) : `${html}${tag}`;
+    },
+  };
+  return plugin;
+}
+
+// SSR on Cloudflare Workers. `output: 'server'` because every response is
+// tenant-resolved at the edge from the Host header (see src/middleware).
+// Preact powers the handful of interactive islands (variant selector, gallery,
+// facets, search typeahead, mobile drawer) — near-zero JS everywhere else.
+export default defineConfig({
+  output: "server",
+  // Externalize all CSS (no auto-inlined <style>) so a strict CSP needs no
+  // inline-style allowance for elements — every stylesheet is a 'self' <link>.
+  // Small first-paint tradeoff, offset by cross-page caching (see LIMITATIONS).
+  build: { inlineStylesheets: "never" },
+  adapter: cloudflare({
+    // Local image/asset placeholders are served from /public; real product
+    // images get rehosted to R2 in Phase 1 ETL (see DECISIONS.md).
+    imageService: "compile",
+  }),
+  integrations: [preact({ compat: true })],
+  vite: {
+    plugins: [tailwindcss(), tenantHotReload(), inlineAiEditPlugin()],
+    // Dev-only: let the dev server accept real tenant Host headers so host-based
+    // tenant routing can be tested locally (e.g. curl -H 'Host: giantvapes.com').
+    // Prod runs on Cloudflare Workers, which has no such allowlist.
+    server: {
+      allowedHosts: [
+        "giantvapes.com",
+        "www.giantvapes.com",
+        "pilot.tokenoftrust.com",
+      ],
+      // Containerized `tot dev` (scripts/dev): a bind-mount often doesn't deliver
+      // inotify events, so Vite's file watcher must POLL for save→HMR to fire.
+      // Gated on CHOKIDAR_USEPOLLING (set by the dev image/compose) so native/local
+      // dev keeps instant, zero-overhead event-based watching. Explicit rather than
+      // relying on Vite auto-reading the env, so it's version-proof.
+      ...(process.env.CHOKIDAR_USEPOLLING
+        ? {
+            watch: {
+              usePolling: true,
+              interval: Number(process.env.CHOKIDAR_INTERVAL) || 300,
+            },
+          }
+        : {}),
+    },
+  },
+  // Canonical/sitemap host comes from the resolved tenant, not here.
+  // `site` is a fallback only used when no tenant context is available.
+  site: "https://pilot.tokenoftrust.com",
+});

package/apps/storefront/env.d.ts

@@ -0,0 +1,155 @@
+/// <reference path="./.astro/types.d.ts" />
+/// <reference types="astro/client" />
+
+import type {
+  TenantConfig,
+  CustomizationEnv,
+  TenantFeatures,
+  ResolvedFoxyCommerce,
+  CapabilityConfig,
+} from "@tot/public-runtime";
+import type { ToTClient } from "@/lib/tot/ToTClient";
+import type { ContentProvider } from "@/lib/storyblok/provider";
+
+/**
+ * Minimal binding shapes. We intentionally do NOT depend on
+ * @cloudflare/workers-types (not installed); these cover what Phase 1 touches.
+ * Widen them when real KV/R2 calls are added.
+ */
+interface KVNamespaceLike {
+  get(key: string, opts?: { cacheTtl?: number }): Promise<string | null>;
+  put(key: string, value: string, opts?: Record<string, unknown>): Promise<void>;
+  list(opts?: { prefix?: string; cursor?: string; limit?: number }): Promise<{
+    keys: { name: string }[];
+    list_complete: boolean;
+    cursor?: string;
+  }>;
+  delete(key: string): Promise<void>;
+}
+interface R2BucketLike {
+  get(key: string): Promise<unknown>;
+  put(key: string, value: unknown): Promise<unknown>;
+}
+
+interface CloudflareEnv {
+  /** Astro session store (adapter default). */
+  SESSION?: KVNamespaceLike;
+  /** Tenant config + catalog cache KV. */
+  TENANT_CACHE?: KVNamespaceLike;
+  /** Rehosted product images. */
+  PRODUCT_IMAGES?: R2BucketLike;
+  /**
+   * Versioned tenant static assets (`public/**`), keyed
+   * `tenants/<id>/<versionId>/<rel>`. Served by src/pages/tenants/[id]/[...path].
+   */
+  TENANT_ASSETS?: R2BucketLike;
+  // Secrets / vars surfaced at runtime.
+  TOT_CATALOG_BASE_URL?: string;
+  TOT_API_KEY?: string;
+  TOT_SECRET_KEY?: string;
+  TOT_ACCESS_TOKEN?: string;
+  PUBLIC_CF_ANALYTICS_TOKEN?: string;
+  /** HMAC secret for signing/verifying customization preview tokens (D4). */
+  CUSTOMIZATION_PREVIEW_SECRET?: string;
+  /**
+   * FoxyCart (Track A). `FOXY_STORE_SUBDOMAIN` overrides the tenant's default
+   * demo store subdomain (swap the demo store with zero code change).
+   * `FOXY_CART_SECRET` is the store's cart-validation secret for signed mode —
+   * absent in the unsigned demo (validation OFF), present on preview/live.
+   */
+  FOXY_STORE_SUBDOMAIN?: string;
+  /** Branded custom checkout domain override (e.g. checkout.preview.tokenoftrust.com). */
+  FOXY_STORE_DOMAIN?: string;
+  FOXY_CART_SECRET?: string;
+}
+
+declare global {
+  // Alias used elsewhere.
+  type KVNamespace = KVNamespaceLike;
+  type R2Bucket = R2BucketLike;
+
+  namespace App {
+    interface Locals {
+      /** Tenant resolved from the request Host by src/middleware. */
+      tenant: TenantConfig;
+      /**
+       * Effective capability flags for the resolved tenant (commerce defaults
+       * unless siteType:"marketing"/explicit features). Chrome, layout islands,
+       * sitemap, and commerce routes gate on these — no tenant-identity checks.
+       */
+      features: TenantFeatures;
+      /** Catalog client bound to the resolved tenant's data scope. */
+      tot: ToTClient;
+      /**
+       * Content provider for this request — overlays any published "Own Your
+       * Look" content for the resolved customizationEnv over Storyblok/local.
+       */
+      content: ContentProvider;
+      /** Inline CSS-variable theme block already serialized for <head>. */
+      themeStyle: string;
+      /** Absolute canonical base for this request. */
+      canonicalBase: string;
+      /**
+       * Path prefix the request was routed under: "" for host-routed requests,
+       * or "/<domain>" when a `/<domain>/*` path segment selected the tenant
+       * (DNS-free local/preview routing). The Layout keeps root-absolute links
+       * inside this prefix on the client.
+       */
+      basePath: string;
+      /**
+       * Which customization environment to serve (D4). "live" on production
+       * hosts; "test" only behind a valid, tenant-bound preview token on a
+       * preview host. Downstream theme/content selection reads this.
+       */
+      customizationEnv: CustomizationEnv;
+      /**
+       * Per-request CSP nonce (D2). Placed on the platform's own inline
+       * <style>/<script is:inline> tags so a strict CSP can allow them without
+       * `unsafe-inline`.
+       */
+      cspNonce: string;
+      /**
+       * Resolved FoxyCart cart/checkout facts for this request (loader src, cart
+       * URL, mode). Present only for commerce tenants with a FoxyCart store;
+       * undefined for marketing tenants or when no store is configured.
+       */
+      commerce?: ResolvedFoxyCommerce;
+      /**
+       * Effective, per-environment capability switches (cart/checkout, age
+       * verification, excise tax) for this request. Resolved from the tenant's
+       * build-time default overridden by the published capabilities artifact for
+       * the current customizationEnv — so the value reflects exactly what a PR
+       * promoted to THIS environment.
+       */
+      capabilities: CapabilityConfig;
+      /**
+       * Signed-in viewer for a login-gated preview host (set by the demo login
+       * gate once a valid, resource-bound `tot_session` cookie is present). Carries
+       * the email + the role(s)/capability tot20 resolved on this tenant, so chrome
+       * can show "signed in as … — owner/developer/staff". Absent on open or
+       * password-gated hosts.
+       */
+      viewer?: {
+        email: string;
+        roles: string[];
+        capability: string;
+      };
+      /** Cloudflare runtime (env bindings) — provided by the adapter on Workers. */
+      runtime?: { env: CloudflareEnv };
+    }
+  }
+}
+
+interface ImportMetaEnv {
+  readonly TOT_CATALOG_BASE_URL?: string;
+  readonly TOT_API_KEY?: string;
+  readonly TOT_SECRET_KEY?: string;
+  readonly TOT_ACCESS_TOKEN?: string;
+  readonly PUBLIC_CF_ANALYTICS_TOKEN?: string;
+  readonly CUSTOMIZATION_PREVIEW_SECRET?: string;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+
+export {};

package/apps/storefront/lib/ensure-preview-reconcile-secret.sh

@@ -0,0 +1,31 @@
+# ensure-preview-reconcile-secret.sh — resolve-or-MINT PREVIEW_RECONCILE_SECRET.
+#
+# ONE secret shared across ALL environments (preview/test/production) — they all
+# point at the same Gitea instance (git.tokenoftrust.com), so there is exactly one
+# webhook-signing secret to keep in sync, not one per tier. SOURCED (not executed)
+# by deploy.sh; idempotent.
+#
+# env wins; else SSM SecureString at /tot/app/storefront/preview-reconcile-secret;
+# else MINT a fresh random value and store it to that SAME SSM param — the first
+# deploy that ever needs it creates it, every deploy after (any environment)
+# resolves the identical value. Silent no-op if aws/openssl are unavailable (the
+# caller then just skips whatever needs this secret, same fail-open shape as the
+# other resolvers in this dir).
+if [ -z "${PREVIEW_RECONCILE_SECRET:-}" ] && command -v aws >/dev/null 2>&1; then
+  _prs_ssm_name="/tot/app/storefront/preview-reconcile-secret"
+  _prs_region="${AWS_REGION:-us-east-1}"
+  _prs_val="$(aws ssm get-parameter --name "$_prs_ssm_name" --with-decryption --region "$_prs_region" --query Parameter.Value --output text 2>/dev/null || true)"
+  if [ -n "$_prs_val" ] && [ "$_prs_val" != "None" ]; then
+    export PREVIEW_RECONCILE_SECRET="$_prs_val"
+    echo "Loaded PREVIEW_RECONCILE_SECRET from SSM ($_prs_ssm_name)"
+  elif command -v openssl >/dev/null 2>&1; then
+    _prs_val="$(openssl rand -hex 32)"
+    if aws ssm put-parameter --name "$_prs_ssm_name" --type SecureString --value "$_prs_val" --region "$_prs_region" --query Version --output text >/dev/null 2>&1; then
+      export PREVIEW_RECONCILE_SECRET="$_prs_val"
+      echo "Minted a new PREVIEW_RECONCILE_SECRET and stored it to SSM ($_prs_ssm_name) — shared across all environments."
+    else
+      echo "Failed to mint/store PREVIEW_RECONCILE_SECRET to SSM ($_prs_ssm_name) — leaving it unset." >&2
+    fi
+  fi
+  unset _prs_val _prs_ssm_name _prs_region
+fi

package/apps/storefront/lib/resolve-cf-token.sh

@@ -0,0 +1,48 @@
+# resolve-cf-token.sh — resolve CLOUDFLARE_API_TOKEN into the environment for
+# Cloudflare CLI/API work. SOURCED (not executed) by provision.sh + deploy.sh so it
+# exports into the caller. Single source of truth for the token + its fallback chain.
+#
+# Precedence: an already-set CLOUDFLARE_API_TOKEN in the env ALWAYS wins (CI injects
+# it that way). Otherwise try each SSM SecureString param named in
+# CLOUDFLARE_API_TOKEN_SSM (space-separated, PRIORITY ORDER), exporting the first
+# that resolves:
+#   1. /tot/cloudflare/provision-token      broad control-plane — R2 + DNS + SSL/Certs
+#                                           + Workers Routes/Scripts + Zone:Read.
+#   2. /tot/cloudflare/storefront-r2-token  FALLBACK — narrower R2 + DNS. Keeps the R2
+#                                           and DNS steps working before the broad
+#                                           token is provisioned. NOTE: under-scoped
+#                                           for SSL-for-SaaS (Step 6) / Workers Routes,
+#                                           so those steps may still skip or warn.
+#
+# Set CLOUDFLARE_API_TOKEN_SSM="" to disable the SSM lookup entirely (e.g. to force
+# wrangler's OAuth). Silent no-op if the token is already set, the aws CLI is absent,
+# or nothing resolves — callers then just skip the CF-dependent steps.
+#
+# Secrets Manager works too: swap the fetch for
+#   aws secretsmanager get-secret-value --secret-id "$_cf_name" --query SecretString --output text
+# Each candidate is VERIFIED with Cloudflare before it's accepted, so a
+# present-but-invalid param (expired/revoked/broken — not just a missing one) falls
+# through to the next in the chain instead of poisoning the run. `/user/tokens/verify`
+# works for any token to check itself. If curl is unavailable, verification is
+# skipped and the first resolvable token is taken as-is.
+_cf_verify() {
+  command -v curl >/dev/null 2>&1 || return 0   # can't verify → accept
+  curl -fsS -H "Authorization: Bearer $1" \
+    https://api.cloudflare.com/client/v4/user/tokens/verify 2>/dev/null \
+    | grep -q '"status":"active"'
+}
+CLOUDFLARE_API_TOKEN_SSM="${CLOUDFLARE_API_TOKEN_SSM-/tot/cloudflare/provision-token /tot/cloudflare/storefront-r2-token}"
+if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] && [ -n "$CLOUDFLARE_API_TOKEN_SSM" ] && command -v aws >/dev/null 2>&1; then
+  for _cf_name in $CLOUDFLARE_API_TOKEN_SSM; do
+    _cf_tok="$(aws ssm get-parameter --name "$_cf_name" --with-decryption --query Parameter.Value --output text 2>/dev/null || true)"
+    [ -n "$_cf_tok" ] && [ "$_cf_tok" != "None" ] || continue
+    if ! _cf_verify "$_cf_tok"; then
+      echo "Skipping $_cf_name — token failed Cloudflare verify (expired/revoked/invalid)"
+      continue
+    fi
+    export CLOUDFLARE_API_TOKEN="$_cf_tok"
+    echo "Loaded CLOUDFLARE_API_TOKEN from SSM ($_cf_name)"
+    break
+  done
+  unset _cf_tok _cf_name
+fi