@tokenoftrust/storefront-runner 0.1.0

package/packages/public-runtime/src/catalog-d1.ts

@@ -0,0 +1,192 @@
+/**
+ * D1 (edge SQLite) catalog read-model — schema + row projections (the one-store
+ * target from epics/edge-read-replica.md). The storefront reads search, faceted
+ * listing, and full products from D1; the ETL emits the rows. This is the shared
+ * contract both sides agree on.
+ *
+ * - `products`         — one row per product: slim query columns + a `data` blob
+ *                        (the full CatalogProduct JSON) for PDP/listing retrieval.
+ * - `product_collections` — membership (handle -> collection handle).
+ * - `product_facets`   — (handle, name, value) for SQL GROUP BY facet counts.
+ * - `products_fts`      — FTS5 (trigram) over the searchable text: typo-tolerant
+ *                        search without loading the catalog into the Worker.
+ */
+import type { CatalogCollection, CatalogProduct } from "./product.js";
+
+export const CATALOG_D1_SCHEMA = `
+CREATE TABLE IF NOT EXISTS products (
+  handle           TEXT PRIMARY KEY NOT NULL,
+  title            TEXT NOT NULL,
+  vendor           TEXT,
+  product_type     TEXT,
+  tags             TEXT NOT NULL DEFAULT '[]',
+  description_text TEXT NOT NULL DEFAULT '',
+  price_min        REAL NOT NULL,
+  price_max        REAL NOT NULL,
+  currency         TEXT NOT NULL,
+  image            TEXT,
+  available        INTEGER NOT NULL DEFAULT 0,
+  status           TEXT NOT NULL,
+  position         INTEGER NOT NULL DEFAULT 0,
+  created_at       TEXT,
+  data             TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS product_collections (
+  handle     TEXT NOT NULL,
+  collection TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pc_collection ON product_collections (collection);
+CREATE TABLE IF NOT EXISTS product_facets (
+  handle TEXT NOT NULL,
+  name   TEXT NOT NULL,
+  value  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pf_name ON product_facets (name, value);
+CREATE TABLE IF NOT EXISTS collections (
+  handle   TEXT PRIMARY KEY NOT NULL,
+  title    TEXT NOT NULL,
+  position INTEGER NOT NULL DEFAULT 99,
+  data     TEXT NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS products_fts USING fts5 (
+  handle UNINDEXED, title, vendor, product_type, tags, description_text,
+  tokenize = 'trigram'
+);
+`.trim();
+
+export interface ProductRow {
+  handle: string;
+  title: string;
+  vendor: string | null;
+  product_type: string | null;
+  tags: string; // JSON array
+  description_text: string;
+  price_min: number;
+  price_max: number;
+  currency: string;
+  image: string | null;
+  available: number; // 0 | 1
+  status: string;
+  position: number;
+  created_at: string | null;
+  data: string; // full CatalogProduct JSON
+}
+
+const firstImage = (p: CatalogProduct): string | null =>
+  (p.images.find((i) => i.url) ?? p.images[0])?.url ?? null;
+
+/** Project a CatalogProduct into the `products` row. */
+export function toProductRow(p: CatalogProduct, position = 0): ProductRow {
+  return {
+    handle: p.handle,
+    title: p.title,
+    vendor: p.vendor ?? null,
+    product_type: p.product_type ?? null,
+    tags: JSON.stringify(p.tags),
+    description_text: p.description_text,
+    price_min: p.price_range.min,
+    price_max: p.price_range.max,
+    currency: p.price_range.currency,
+    image: firstImage(p),
+    available: p.variants.some((v) => v.inventory.available) ? 1 : 0,
+    status: p.status,
+    position,
+    created_at: p.created_at,
+    data: JSON.stringify(p),
+  };
+}
+
+/** Facet rows: one per distinct option value (across variants) + one per tag. */
+export function facetRows(p: CatalogProduct): Array<{ name: string; value: string }> {
+  const out: Array<{ name: string; value: string }> = [];
+  for (const opt of p.options) {
+    const seen = new Set<string>();
+    for (const v of p.variants) {
+      const val = v.option_values[opt.name];
+      if (val && !seen.has(val)) {
+        seen.add(val);
+        out.push({ name: opt.name, value: val });
+      }
+    }
+  }
+  for (const tag of p.tags) out.push({ name: "tags", value: tag });
+  return out;
+}
+
+/** Collection-membership rows for a product. */
+export function collectionRows(p: CatalogProduct): Array<{ collection: string }> {
+  return p.collections.map((collection) => ({ collection }));
+}
+
+export interface CollectionRow {
+  handle: string;
+  title: string;
+  position: number;
+  data: string;
+}
+
+/** Project a CatalogCollection into the `collections` row. */
+export function toCollectionRow(c: CatalogCollection): CollectionRow {
+  return {
+    handle: c.handle,
+    title: c.title,
+    position: c.position ?? 99,
+    data: JSON.stringify(c),
+  };
+}
+
+/** SQL literal: NULL, a number, or a single-quote-escaped string. */
+function lit(v: string | number | null): string {
+  if (v === null) return "NULL";
+  if (typeof v === "number") return Number.isFinite(v) ? String(v) : "NULL";
+  return `'${v.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Emit a self-contained SQL seed (schema + a clean reseed of all rows) for a
+ * tenant, loadable into D1 via `wrangler d1 execute <DB> --file catalog.sql`.
+ * Includes ALL products (status column drives query visibility; getProductByHandle
+ * still resolves drafts). Re-runnable: it clears the tables before inserting.
+ */
+export function emitCatalogSql(
+  products: CatalogProduct[],
+  collections: CatalogCollection[] = [],
+): string {
+  const out: string[] = [
+    CATALOG_D1_SCHEMA,
+    "DELETE FROM products;",
+    "DELETE FROM product_collections;",
+    "DELETE FROM product_facets;",
+    "DELETE FROM products_fts;",
+    "DELETE FROM collections;",
+  ];
+  for (const c of collections) {
+    const r = toCollectionRow(c);
+    out.push(
+      `INSERT INTO collections (handle,title,position,data) VALUES (${[r.handle, r.title, r.position, r.data].map(lit).join(",")});`,
+    );
+  }
+  let position = 0;
+  for (const p of products) {
+    const r = toProductRow(p, position++);
+    out.push(
+      `INSERT INTO products (handle,title,vendor,product_type,tags,description_text,price_min,price_max,currency,image,available,status,position,created_at,data) VALUES (${[
+        r.handle, r.title, r.vendor, r.product_type, r.tags, r.description_text,
+        r.price_min, r.price_max, r.currency, r.image, r.available, r.status,
+        r.position, r.created_at, r.data,
+      ].map(lit).join(",")});`,
+    );
+    out.push(
+      `INSERT INTO products_fts (handle,title,vendor,product_type,tags,description_text) VALUES (${[
+        p.handle, p.title, p.vendor ?? "", p.product_type ?? "", p.tags.join(" "), p.description_text,
+      ].map(lit).join(",")});`,
+    );
+    for (const f of facetRows(p)) {
+      out.push(`INSERT INTO product_facets (handle,name,value) VALUES (${lit(p.handle)},${lit(f.name)},${lit(f.value)});`);
+    }
+    for (const c of collectionRows(p)) {
+      out.push(`INSERT INTO product_collections (handle,collection) VALUES (${lit(p.handle)},${lit(c.collection)});`);
+    }
+  }
+  return `${out.join("\n")}\n`;
+}

package/packages/public-runtime/src/csp.ts

@@ -0,0 +1,109 @@
+/**
+ * Content-Security-Policy builder. Pure + dep-free so it's unit-testable and
+ * reusable across the storefront.
+ *
+ * Produces a strict policy: `default-src 'self'`, no `unsafe-inline`. The
+ * platform's own inline `<style>`/`<script is:inline>` are allowed via a
+ * per-request nonce; everything else must be `'self'`, an explicitly allowlisted
+ * host, or (for tenant scripts) a per-version hash passed in `scriptSrc`.
+ *
+ * The middleware decides the header name — `Content-Security-Policy` (enforce)
+ * vs `Content-Security-Policy-Report-Only` (rollout). This only builds the value.
+ */
+export interface CspOptions {
+  /** Per-request nonce; the same value goes on the platform's inline tags. */
+  nonce: string;
+  /** Extra script-src entries: allowlisted CDNs + per-version tenant hashes. */
+  scriptSrc?: readonly string[];
+  styleSrc?: readonly string[];
+  fontSrc?: readonly string[];
+  imgSrc?: readonly string[];
+  connectSrc?: readonly string[];
+  /** Sandboxed-widget origins. */
+  frameSrc?: readonly string[];
+  /**
+   * Extra `form-action` targets. Default is `'self'`; the FoxyCart add-to-cart
+   * form POSTs cross-origin to the store's `/cart`, so that origin is added here.
+   */
+  formAction?: readonly string[];
+  /** Reporting group name for `report-to` (paired with a Reporting-Endpoints header). */
+  reportGroup?: string;
+  /** Legacy `report-uri` path (broader browser support during rollout). */
+  reportUri?: string;
+}
+
+export function buildCsp(opts: CspOptions): string {
+  const nonce = `'nonce-${opts.nonce}'`;
+  const directives: Record<string, string[]> = {
+    "default-src": ["'self'"],
+    "base-uri": ["'self'"],
+    "object-src": ["'none'"],
+    "frame-ancestors": ["'self'"],
+    "form-action": ["'self'", ...(opts.formAction ?? [])],
+    "script-src": ["'self'", nonce, ...(opts.scriptSrc ?? [])],
+    "style-src": ["'self'", nonce, ...(opts.styleSrc ?? [])],
+    // Inline style ATTRIBUTES (style="…") can't carry a nonce; CSS can't execute
+    // JS, so this is the one tolerated relaxation. style-src-elem still inherits
+    // the strict 'self'+nonce from style-src; script-src stays fully strict.
+    "style-src-attr": ["'unsafe-inline'"],
+    "font-src": ["'self'", ...(opts.fontSrc ?? [])],
+    "img-src": ["'self'", "data:", ...(opts.imgSrc ?? [])],
+    "connect-src": ["'self'", ...(opts.connectSrc ?? [])],
+    "frame-src": ["'self'", ...(opts.frameSrc ?? [])],
+  };
+  const parts = Object.entries(directives).map(
+    ([name, values]) => `${name} ${values.join(" ")}`,
+  );
+  if (opts.reportUri) parts.push(`report-uri ${opts.reportUri}`);
+  if (opts.reportGroup) parts.push(`report-to ${opts.reportGroup}`);
+  return parts.join("; ");
+}
+
+/** Endpoint that collects CSP violation reports during the report-only rollout. */
+export const CSP_REPORT_PATH = "/api/csp-report";
+export const CSP_REPORT_GROUP = "csp-endpoint";
+
+/**
+ * The storefront's known-good external origins. The middleware passes these to
+ * `buildCsp` and may extend `scriptSrc` (tenant hashes) + `frameSrc` (the widget
+ * origin) per request.
+ */
+export const STOREFRONT_CSP_ALLOWLIST = {
+  scriptSrc: ["https://static.cloudflareinsights.com"],
+  styleSrc: ["https://fonts.googleapis.com"],
+  fontSrc: ["https://fonts.gstatic.com"],
+  // Product imagery is rehosted to R2 or served from remote CDNs.
+  imgSrc: ["https:"],
+  connectSrc: ["https://cloudflareinsights.com"],
+} as const;
+
+/**
+ * CSP additions for a FoxyCart-enabled tenant. The loader.js comes from
+ * `cdn.foxycart.com`; the sidecart XHR + iframe + the add-to-cart form POST all
+ * hit the store's own origin (`<store>.foxycart.com` or a branded checkout
+ * domain). Merge these into `buildCsp` per request when `locals.commerce.foxy`
+ * is present so the strict policy still passes.
+ */
+export function foxyCspAdditions(storeOrigin: string): {
+  scriptSrc: string[];
+  styleSrc: string[];
+  fontSrc: string[];
+  connectSrc: string[];
+  frameSrc: string[];
+  formAction: string[];
+  imgSrc: string[];
+} {
+  const cdn = "https://cdn.foxycart.com";
+  // Foxy's loader pulls its own JS, CSS, and fonts from the CDN and renders the
+  // sidecart/checkout from the store origin — so it needs script/style/font from
+  // the CDN and connect/frame/form to the store.
+  return {
+    scriptSrc: [cdn, storeOrigin],
+    styleSrc: [cdn, storeOrigin],
+    fontSrc: [cdn, storeOrigin],
+    connectSrc: [cdn, storeOrigin],
+    frameSrc: [cdn, storeOrigin],
+    formAction: [storeOrigin],
+    imgSrc: [cdn, storeOrigin],
+  };
+}

package/packages/public-runtime/src/customization-preview.ts

@@ -0,0 +1,197 @@
+/**
+ * Gated preview support: signing preview access and resolving which
+ * customization environment a request sees.
+ *
+ * Two pure, runtime-portable pieces (Web Crypto + btoa/atob, no `node:*`):
+ *
+ *   1. signed, short-TTL **preview tokens** (HMAC-SHA256) that grant access to a
+ *      tenant's `test` customization on a preview host; and
+ *   2. `resolveCustomizationEnv` — the live-vs-test decision the middleware makes
+ *      per request.
+ *
+ * Security properties this enforces:
+ *   - **Production hosts never serve `test`.** A token is only consulted on a
+ *     preview host, so a leaked token can't flip a live storefront.
+ *   - **Tokens are tenant-bound.** A token minted for tenant A cannot preview
+ *     tenant B (no cross-tenant leakage).
+ *   - **Tokens expire.** `exp` is checked against the caller-supplied clock.
+ *   - **Test is never indexable.** The resolution carries `noindex: true` so the
+ *     middleware can set `X-Robots-Tag: noindex`.
+ */
+
+/** Claims carried by a preview token. */
+export interface PreviewClaims {
+  tenantId: string;
+  env: "test";
+  /** Expiry, epoch seconds. */
+  exp: number;
+}
+
+const textEncoder = new TextEncoder();
+
+function bytesToB64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64UrlToBytes(s: string): Uint8Array {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+  const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/") + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    textEncoder.encode(secret) as unknown as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+/**
+ * Mint a preview token: `<payloadB64Url>.<sigB64Url>`. `ttlSeconds` is added to
+ * `nowSeconds` (caller supplies the clock so this stays pure/testable).
+ */
+export async function signPreviewToken(
+  secret: string,
+  tenantId: string,
+  ttlSeconds: number,
+  nowSeconds: number,
+): Promise<string> {
+  const claims: PreviewClaims = {
+    tenantId,
+    env: "test",
+    exp: nowSeconds + ttlSeconds,
+  };
+  const payload = bytesToB64Url(textEncoder.encode(JSON.stringify(claims)));
+  const key = await hmacKey(secret);
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    textEncoder.encode(payload) as unknown as BufferSource,
+  );
+  return `${payload}.${bytesToB64Url(new Uint8Array(sig))}`;
+}
+
+export type VerifyResult =
+  | { ok: true; claims: PreviewClaims }
+  | { ok: false; reason: "malformed" | "bad-signature" | "expired" };
+
+/**
+ * Verify a preview token against `secret` and the caller's clock. Signature is
+ * checked with `crypto.subtle.verify` (constant-time) before expiry.
+ */
+export async function verifyPreviewToken(
+  secret: string,
+  token: string,
+  nowSeconds: number,
+): Promise<VerifyResult> {
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: "malformed" };
+  const payload = token.slice(0, dot);
+  const sigPart = token.slice(dot + 1);
+
+  let sig: Uint8Array;
+  try {
+    sig = b64UrlToBytes(sigPart);
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const key = await hmacKey(secret);
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig as unknown as BufferSource,
+    textEncoder.encode(payload) as unknown as BufferSource,
+  );
+  if (!valid) return { ok: false, reason: "bad-signature" };
+
+  let claims: PreviewClaims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(b64UrlToBytes(payload)));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (
+    !claims ||
+    claims.env !== "test" ||
+    typeof claims.tenantId !== "string" ||
+    typeof claims.exp !== "number"
+  ) {
+    return { ok: false, reason: "malformed" };
+  }
+  if (claims.exp <= nowSeconds) return { ok: false, reason: "expired" };
+  return { ok: true, claims };
+}
+
+export type CustomizationEnv = "live" | "test";
+
+export interface EnvResolutionInput {
+  /** True when the request arrived on a preview host (e.g. `preview.*`). */
+  isPreviewHost: boolean;
+  /** The tenant resolved for this request. */
+  tenantId: string;
+  /** Token from `?__preview=` or the `tot_preview` cookie, if any. */
+  token?: string | null;
+  /** Platform preview-signing secret (env), if configured. */
+  secret?: string | null;
+  nowSeconds: number;
+}
+
+export interface EnvResolution {
+  env: CustomizationEnv;
+  /** Set `X-Robots-Tag: noindex` when true (test is never indexable). */
+  noindex: boolean;
+  /** When set, the middleware should short-circuit with this status. */
+  reject?: { status: number; message: string };
+}
+
+/**
+ * Decide which customization environment to serve. Production hosts always get
+ * `live` and never consult a token. Preview hosts are auth-gated: a valid,
+ * unexpired, tenant-matching token yields `test` (noindex); anything else is
+ * rejected.
+ */
+export async function resolveCustomizationEnv(
+  input: EnvResolutionInput,
+): Promise<EnvResolution> {
+  if (!input.isPreviewHost) {
+    return { env: "live", noindex: false };
+  }
+  if (!input.secret) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 503, message: "Preview is not configured." },
+    };
+  }
+  if (!input.token) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 401, message: "Preview token required." },
+    };
+  }
+  const result = await verifyPreviewToken(input.secret, input.token, input.nowSeconds);
+  if (!result.ok) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 401, message: `Invalid preview token (${result.reason}).` },
+    };
+  }
+  if (result.claims.tenantId !== input.tenantId) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 403, message: "Preview token is for a different tenant." },
+    };
+  }
+  return { env: "test", noindex: true };
+}

package/packages/public-runtime/src/customization-reconcile.ts

@@ -0,0 +1,63 @@
+/**
+ * Types for the tenant preview model: the `.tot/config.json` mapping shape and
+ * the preview-state record — which commit a tenant's preview targets vs. what is
+ * currently rendered — plus its KV key. Read-only shapes; no logic here.
+ */
+
+/** Repo-relative path of the tenant repo's mapping config. */
+export const TOT_CONFIG_PATH = ".tot/config.json";
+
+/** One mapping from a tenant-repo prefix to a storefront artifact path. */
+export interface TotRepoMapping {
+  /** Tenant-repo path/prefix (e.g. "theme.json", "content/", "public/"). */
+  workspace: string;
+  /** Storefront artifact path/prefix it maps to. */
+  repo: string;
+  kind: "file" | "tree";
+}
+export interface TotRepoConfig {
+  tenant: string;
+  scope?: string;
+  mappings: TotRepoMapping[];
+}
+
+/** One compliance check row (mirrors @tot/private-controlplane's EvidenceCheck —
+ * kept structural here so this read-only type stays dependency-free). */
+export interface PreviewStateEvidenceCheck {
+  id: string;
+  label: string;
+  status: string;
+  detail?: string;
+  /** A concrete fix suggestion for a non-pass check (evidence producer's own —
+   * the same "why" + "fix" the CLI's `tot submit --watch` prints). */
+  hint?: string;
+  /** Whether this check is ship-blocking (REQUIRED_FOR_PROMOTE). Computed at
+   * merge time (preview-state-evidence.ts), not stored by the producer. */
+  required?: boolean;
+}
+
+/** Fail-safe preview state — target/actual can diverge when target is broken. */
+export interface PreviewState {
+  tenantId: string;
+  /** The commit the dev wants previewed. */
+  target: string | null;
+  /** The commit currently rendered (last successfully materialized). */
+  actual: string | null;
+  /** Why target != actual, when the target failed to render. Null on success. */
+  lastError: string | null;
+  lastReconcileAt: string | null;
+  /**
+   * The compliance verdict for the last successful reconcile (ADR 0010's evidence,
+   * mirrored here so the PUBLIC, unauthenticated /preview/dashboard page can show
+   * it — a shareable link should be as informative as the CLI's, without an MCP
+   * round trip). Optional/absent on a record `reconcilePreview` itself wrote
+   * (that pipeline doesn't know about evidence) — only the reconcile ROUTE's
+   * post-hoc merge sets it, after `reportPreviewEvidence` computes it. Absent and
+   * `null` both mean "no verdict yet"; callers should treat them the same.
+   */
+  evidence?: { checks: PreviewStateEvidenceCheck[]; promotable: boolean; generatedAt: string } | null;
+}
+
+export function previewStateKey(tenantId: string): string {
+  return `cust:preview-state:${tenantId}`;
+}