@tokenoftrust/storefront-runner 1.3.2

package/packages/public-runtime/src/checkout-style-publish.ts

@@ -0,0 +1,200 @@
+/**
+ * Signed storefront → FoxyCart theme-publish client (U11b, the PUSH half of U11).
+ *
+ * Points a store's Foxy checkout template at the storefront-hosted stylesheet
+ * (`GET /api/checkout-style.css`, U11) by driving tot-foxycart's `/theme/foxy`
+ * endpoint: PUT the `content_url`, then POST `/refresh` (PUT alone only sets the
+ * pointer — Foxy caches the template, so nothing goes live until refresh).
+ *
+ * AUTH: each request carries an `x-tot-signature` header = lowercase-hex
+ * HMAC-SHA256 of `JSON.stringify(body)` keyed by the STORE'S ToT SECRET KEY —
+ * byte-identical to tot-foxycart's `foxyStore.verifyWebhookSignature`. That
+ * secret is the storefront's `TOT_SECRET_KEY`; this is independent of the
+ * FoxyCart hAPI credentials (see decision `u11b-not-blocked-by-u7`).
+ *
+ * Edge-safe + node-free (WebCrypto HMAC); the network call is injected so the
+ * flow is fully unit-testable offline. The caller (the checkout-styling promote
+ * hook — U13) supplies the resolved secret + base URL from server context; the
+ * secret is never shipped to the client.
+ */
+import type { CustomizationEnv } from "./customization-preview.js";
+
+/** Header tot-foxycart reads the HMAC from (matches foxyThemeEndpoint SIGNATURE_HEADER). */
+export const TOT_SIGNATURE_HEADER = "x-tot-signature";
+
+/** Foxy caps content_url at 300 chars; '' detaches the template (revert to default). */
+export const MAX_CONTENT_URL = 300;
+
+/** Fetch shape we depend on — the platform `fetch`, injectable for tests. */
+export type FetchLike = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  },
+) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;
+
+export interface ThemePublishTarget {
+  /** tot-foxycart proxy base, e.g. `https://foxycart-test.tokenoftrust.com`. */
+  foxyBaseUrl: string;
+  /** The store's app domain / subdomain (tot-foxycart resolves the store from it). */
+  appDomain: string;
+  /** The hosted stylesheet URL Foxy will fetch (U11's `/api/checkout-style.css`). */
+  contentUrl: string;
+  /** The store's ToT secret key (storefront `TOT_SECRET_KEY`) — signs the request. */
+  secret: string;
+  /** Foxy template to target; checkout styling uses `checkout` (the default). */
+  templateType?: string;
+}
+
+export interface ThemePublishResult {
+  ok: boolean;
+  /** Parsed PUT response (pointer set), when it succeeded. */
+  set?: unknown;
+  /** Parsed refresh response (cache re-pulled), when it succeeded. */
+  refreshed?: boolean;
+  /** Failure detail: which step + the endpoint's status/message. */
+  error?: string;
+}
+
+/** Lowercase-hex HMAC-SHA256(message) under `secret` (WebCrypto). Matches foxy.ts. */
+async function hmacHex(secret: string, message: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(message));
+  return [...new Uint8Array(sig)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * The exact signature tot-foxycart verifies: hex HMAC-SHA256 of the JSON body
+ * string under the store secret. Exported so the promote hook and tests can
+ * compute/assert it identically.
+ */
+export function signThemeRequestBody(
+  secret: string,
+  body: unknown,
+): Promise<string> {
+  return hmacHex(secret, JSON.stringify(body));
+}
+
+/**
+ * The canonical, stable content_url a store's checkout template points at — the
+ * U11 route on the store's own host, so Foxy's server-side fetch self-identifies
+ * the tenant + env. Returns null if it would exceed Foxy's 300-char cap (so the
+ * caller surfaces a config error rather than pushing a URL Foxy will reject).
+ */
+export function checkoutStyleContentUrl(
+  host: string,
+  basePath = "",
+): string | null {
+  const url = `https://${host}${basePath}/api/checkout-style.css`;
+  return url.length <= MAX_CONTENT_URL ? url : null;
+}
+
+async function readErr(
+  res: { status: number; text: () => Promise<string> },
+  step: string,
+): Promise<string> {
+  let detail = "";
+  try {
+    detail = (await res.text()).slice(0, 300);
+  } catch {
+    /* ignore */
+  }
+  return `${step} failed (HTTP ${res.status})${detail ? `: ${detail}` : ""}`;
+}
+
+/**
+ * Publish a store's checkout styling to Foxy: signed PUT `/theme/foxy` then
+ * signed POST `/theme/foxy/refresh`. Returns a discriminated result — we do NOT
+ * fail open: if the PUT fails we skip the refresh and report the error, so the
+ * caller never reports "published" for something that didn't take.
+ *
+ * `fetchImpl` defaults to the global `fetch`; tests inject a stub.
+ */
+export async function publishCheckoutTheme(
+  target: ThemePublishTarget,
+  fetchImpl?: FetchLike,
+): Promise<ThemePublishResult> {
+  const doFetch = fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
+  const templateType = target.templateType ?? "checkout";
+  const base = target.foxyBaseUrl.replace(/\/+$/, "");
+
+  if (
+    target.contentUrl !== "" &&
+    (!target.contentUrl.startsWith("https://") ||
+      target.contentUrl.length > MAX_CONTENT_URL)
+  ) {
+    return {
+      ok: false,
+      error: `invalid contentUrl (must be https and <= ${MAX_CONTENT_URL} chars)`,
+    };
+  }
+
+  // 1. PUT the pointer.
+  const setBody = {
+    appDomain: target.appDomain,
+    templateType,
+    contentUrl: target.contentUrl,
+  };
+  const setSig = await signThemeRequestBody(target.secret, setBody);
+  const setRes = await doFetch(`${base}/theme/foxy`, {
+    method: "PUT",
+    headers: {
+      "content-type": "application/json",
+      [TOT_SIGNATURE_HEADER]: setSig,
+    },
+    body: JSON.stringify(setBody),
+  });
+  if (!setRes.ok) {
+    return { ok: false, error: await readErr(setRes, "PUT /theme/foxy") };
+  }
+  let set: unknown = undefined;
+  try {
+    set = JSON.parse(await setRes.text());
+  } catch {
+    /* non-JSON ok-body — leave undefined */
+  }
+
+  // 2. POST refresh to make it live.
+  const refreshBody = { appDomain: target.appDomain, templateType };
+  const refreshSig = await signThemeRequestBody(target.secret, refreshBody);
+  const refreshRes = await doFetch(`${base}/theme/foxy/refresh`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      [TOT_SIGNATURE_HEADER]: refreshSig,
+    },
+    body: JSON.stringify(refreshBody),
+  });
+  if (!refreshRes.ok) {
+    return {
+      ok: false,
+      set,
+      error: await readErr(refreshRes, "POST /theme/foxy/refresh"),
+    };
+  }
+
+  return { ok: true, set, refreshed: true };
+}
+
+/**
+ * Convenience: the env → Foxy-proxy base URL for this workstream's targets.
+ * qa runs NODE_ENV=test (proxy `foxycart-test`); sandbox → `foxycart-sandbox`;
+ * live → the prod proxy. Kept here so the promote hook (U13) resolves one place.
+ */
+export function foxyProxyBaseUrl(env: CustomizationEnv): string {
+  // "test" is the qa target's env; "live" is prod.
+  return env === "live"
+    ? "https://foxycart.tokenoftrust.com"
+    : "https://foxycart-test.tokenoftrust.com";
+}

package/packages/public-runtime/src/checkout-style.ts

@@ -0,0 +1,375 @@
+/**
+ * Checkout-styling data model + published-artifact read plumbing.
+ *
+ * The FoxyCart-hosted checkout is styled by CSS pushed to Foxy's `/theme/foxy`
+ * endpoint (U11). This module owns the *source of truth* for that styling: a
+ * small, structured, tenant-editable descriptor that later units render into
+ * ASCII-safe CSS. It sits on the SAME versioned publish spine as theme/content
+ * (D1VersionStore + KV pointers) — resolution is per-environment via
+ * `readPublishedArtifact`, so a merchant's draft previews on `test` and the
+ * promoted style serves on `live`, exactly like the theme artifact.
+ *
+ * Two colocated artifacts under `tenants/<id>/`:
+ *   - `checkout-style.json` — the structured `CheckoutStyle` descriptor (below).
+ *   - `checkout.css`        — an optional raw-CSS escape hatch a merchant edits
+ *                             directly; hosted + pushed to Foxy as-is (U11).
+ *
+ * Pure + dependency-free (node-free, edge-safe): the caller injects the same
+ * `KvGet` used for theme/content, keeping this unit-testable and storage-agnostic.
+ * No UI here — that's U12.
+ */
+import type { CustomizationEnv } from "./customization-preview.js";
+import type { DeepPartial, ThemeTokens } from "./tenant.js";
+import { readPublishedArtifact, type KvGet } from "./customization-runtime.js";
+
+/**
+ * Color levers exposed on the checkout page. Deliberately a small, opinionated
+ * subset of the full theme palette — the checkout is a focused conversion
+ * surface, not the whole store. All values are CSS colors; hex is validated for
+ * WCAG contrast downstream (U13 gate), non-hex (e.g. `rgb(...)`) is passed
+ * through. Keep values ASCII-safe — Foxy's cache pass isn't Unicode-safe.
+ */
+export interface CheckoutStyleColors {
+  /** Page background behind the checkout card. */
+  background: string;
+  /** Surface color of the checkout card / form panels. */
+  surface: string;
+  /** Primary brand color — section headings and the pay button fill. */
+  primary: string;
+  /** Foreground on `primary` (button label / on-primary text) — contrast pair. */
+  primaryContrast: string;
+  /** Accent color — links, focus rings, selected states. */
+  accent: string;
+  /** Body text color. */
+  text: string;
+}
+
+/**
+ * Typography for the checkout page. `fontFamily` is a full CSS font-family stack
+ * (a web-safe stack, or a Foxy-supported webfont name plus fallbacks) — kept as
+ * an opaque string so a merchant can bring their own stack without a schema bump.
+ */
+export interface CheckoutStyleTypography {
+  /** CSS font-family stack, e.g. `"Inter", system-ui, sans-serif`. */
+  fontFamily: string;
+  /** Base font size as a CSS length, e.g. `16px`. */
+  baseSize: string;
+}
+
+/** Button/control shape on the checkout. */
+export interface CheckoutStyleButton {
+  /** Corner radius as a CSS length, e.g. `6px` (`0` for square). */
+  radius: string;
+}
+
+/**
+ * The structured checkout-styling descriptor — the `checkout-style.json`
+ * artifact. This is the model a merchant edits (U12) and that U11 renders into
+ * the CSS pushed to Foxy. A published artifact is a `DeepPartial` of this
+ * (a merchant may set one field without restating the rest); `resolveCheckout
+ * Style` merges it over `DEFAULT_CHECKOUT_STYLE` so the resolved value is always
+ * complete.
+ */
+export interface CheckoutStyle {
+  colors: CheckoutStyleColors;
+  typography: CheckoutStyleTypography;
+  button: CheckoutStyleButton;
+  /** Optional logo URL shown on the checkout header (absolute https URL). */
+  logoUrl?: string;
+}
+
+/**
+ * Neutral, accessible baseline used when a tenant publishes nothing (or omits a
+ * field). Chosen for AA contrast on the default pairs so an un-styled checkout
+ * is never broken — a merchant only overrides what they want to change.
+ */
+export const DEFAULT_CHECKOUT_STYLE: CheckoutStyle = {
+  colors: {
+    background: "#ffffff",
+    surface: "#f7f7f8",
+    primary: "#111111",
+    primaryContrast: "#ffffff",
+    accent: "#2563eb",
+    text: "#1a1a1a",
+  },
+  typography: {
+    fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+    baseSize: "16px",
+  },
+  button: {
+    radius: "6px",
+  },
+};
+
+/**
+ * Derive a checkout style FROM a tenant's brand `ThemeTokens`, so the checkout is
+ * consistent with the look/feel the merchant already chose for the storefront
+ * instead of a neutral default. This is the "from theme" seam: the settings editor
+ * (U12) seeds a merchant's starting style from it, and a tenant that ships a brand
+ * theme gets an in-brand checkout with no hand-authoring.
+ *
+ * It maps the small, opinionated checkout surface onto the full theme palette:
+ *   - colors ← `color.{bg,surface,primary,primary-contrast,accent,text}`
+ *   - typography.fontFamily ← the theme's BODY family, expanded into a web-safe
+ *     stack (the checkout is body copy + a CTA, not display type)
+ *   - button.radius ← `shape.radius.md` (the standard control radius)
+ *   - logoUrl ← `brand.logoLight`, but ONLY when it is an absolute https URL —
+ *     Foxy fetches the checkout server-side, so a repo-relative logo path
+ *     (e.g. `/brand/logo.svg`) can't resolve there and is dropped.
+ *
+ * Input is a `DeepPartial` (a tenant's `theme.json` override is sparse), so every
+ * field falls back to `DEFAULT_CHECKOUT_STYLE` when the theme omits it — the result
+ * is always a complete `CheckoutStyle`. ASCII discipline (Foxy's cache is not
+ * Unicode-safe): any derived string leaf that isn't `isAsciiSafe` is dropped in
+ * favor of the default, so a theme can never produce a checkout-blanking value.
+ * Pure + node-free.
+ */
+export function checkoutStyleFromTheme(
+  theme: DeepPartial<ThemeTokens> | null | undefined,
+): CheckoutStyle {
+  const d = DEFAULT_CHECKOUT_STYLE;
+  // Take a theme string only when it is a non-empty, ASCII-safe scalar; otherwise
+  // fall back so a missing/exotic token never yields a bad checkout value.
+  const take = (value: unknown, fallback: string): string =>
+    typeof value === "string" && value.trim() && isAsciiSafe(value)
+      ? value
+      : fallback;
+
+  const color = theme?.color;
+  const shape = theme?.shape;
+  const bodyFamily = theme?.type?.body?.family;
+  const logo = theme?.brand?.logoLight;
+
+  return {
+    colors: {
+      background: take(color?.bg, d.colors.background),
+      surface: take(color?.surface, d.colors.surface),
+      primary: take(color?.primary, d.colors.primary),
+      primaryContrast: take(color?.["primary-contrast"], d.colors.primaryContrast),
+      accent: take(color?.accent, d.colors.accent),
+      text: take(color?.text, d.colors.text),
+    },
+    typography: {
+      fontFamily: fontStackFromFamily(bodyFamily, d.typography.fontFamily),
+      baseSize: d.typography.baseSize,
+    },
+    button: {
+      radius: take(shape?.radius?.md, d.button.radius),
+    },
+    ...(typeof logo === "string" &&
+    isAsciiSafe(logo) &&
+    /^https:\/\/\S+$/.test(logo.trim())
+      ? { logoUrl: logo.trim() }
+      : {}),
+  };
+}
+
+/**
+ * Expand a single theme font FAMILY (`"Inter"`) into a full CSS font-family stack
+ * with web-safe fallbacks — the checkout must render legibly even where the brand
+ * webfont isn't loaded. A value that already looks like a stack (has a comma) is
+ * used as-is. Falls back to `fallback` when the family is absent or non-ASCII.
+ */
+function fontStackFromFamily(family: unknown, fallback: string): string {
+  if (typeof family !== "string" || !family.trim() || !isAsciiSafe(family)) {
+    return fallback;
+  }
+  const f = family.trim();
+  if (f.includes(",")) return f;
+  const quoted = /\s/.test(f) ? `"${f}"` : f;
+  return `${quoted}, system-ui, -apple-system, Segoe UI, Roboto, sans-serif`;
+}
+
+/**
+ * Canonical published-artifact path for a tenant's structured checkout style.
+ * Same colocated `tenants/<id>/…` contract as theme/capabilities, so the
+ * reconcile pipeline keys the KV artifact by it and the storefront reads it back
+ * per environment.
+ */
+export function checkoutStyleArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/checkout-style.json`;
+}
+
+/**
+ * Canonical path for the optional raw-CSS override artifact — the escape hatch a
+ * merchant edits directly (or that advanced templates ship). Sibling to the
+ * structured descriptor; hosted + pushed to Foxy verbatim by U11.
+ */
+export function checkoutStyleCssPath(tenantId: string): string {
+  return `tenants/${tenantId}/checkout.css`;
+}
+
+/**
+ * Safely parse a published `checkout-style.json` string into a partial override.
+ * Never throws — returns null on malformed JSON or a non-object top level, so the
+ * caller falls back to the default (mirrors the theme read path's tolerance).
+ */
+export function parseCheckoutStyle(
+  raw: string | null,
+): DeepPartial<CheckoutStyle> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as DeepPartial<CheckoutStyle>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deep-merge a partial override over a complete base, so a merchant can set one
+ * field without restating the rest. Objects merge recursively; scalars replace.
+ * Node-free and self-contained (mirrors `mergeTheme`'s deepMerge).
+ */
+export function mergeCheckoutStyle(
+  base: CheckoutStyle,
+  override?: DeepPartial<CheckoutStyle> | null,
+): CheckoutStyle {
+  if (!override) return base;
+  return deepMerge(base, override) as CheckoutStyle;
+}
+
+function deepMerge<T>(base: T, over: DeepPartial<T>): T {
+  if (typeof base === "object" && base !== null && !Array.isArray(base)) {
+    const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+    for (const [k, v] of Object.entries(over as Record<string, unknown>)) {
+      if (v === undefined) continue;
+      const bv = (base as Record<string, unknown>)[k];
+      out[k] =
+        bv && typeof bv === "object" && !Array.isArray(bv) && typeof v === "object"
+          ? deepMerge(bv, v as DeepPartial<unknown>)
+          : v;
+    }
+    return out as T;
+  }
+  return (over as unknown as T) ?? base;
+}
+
+/**
+ * Resolve a tenant's effective checkout style for an environment: the
+ * `DEFAULT_CHECKOUT_STYLE` baseline with any published `checkout-style.json`
+ * override merged on top. Reads through the versioned publish spine (channel →
+ * version → artifact) via `readPublishedArtifact`; a malformed/absent artifact
+ * degrades to the default. Never throws.
+ */
+export async function resolveCheckoutStyle(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+): Promise<CheckoutStyle> {
+  const raw = await readPublishedArtifact(
+    get,
+    tenantId,
+    env,
+    checkoutStyleArtifactPath(tenantId),
+  );
+  return mergeCheckoutStyle(DEFAULT_CHECKOUT_STYLE, parseCheckoutStyle(raw));
+}
+
+/**
+ * Resolve a tenant's published raw checkout CSS override for an environment, or
+ * null when none is published (so U11 pushes only the generated tokens). Reads
+ * the sibling `checkout.css` artifact through the same versioned spine. Never
+ * throws.
+ */
+export async function resolveCheckoutStyleCss(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+): Promise<string | null> {
+  return readPublishedArtifact(
+    get,
+    tenantId,
+    env,
+    checkoutStyleCssPath(tenantId),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// CSS serialization (the artifact pushed to FoxyCart) — U11
+// ---------------------------------------------------------------------------
+
+/**
+ * True iff every character is 7-bit ASCII (code point < 128). FoxyCart's
+ * template cache pass is NOT Unicode-safe — a non-ASCII byte in the cached
+ * checkout content yields a BLANK page. So the publisher (U11) MUST gate both
+ * the generated token CSS and any raw override through this before pushing a
+ * `content_url` to `/theme/foxy`. We reject rather than transliterate, so a
+ * merchant is told to fix their input instead of getting silently-mangled CSS.
+ */
+export function isAsciiSafe(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    if (s.charCodeAt(i) > 127) return false;
+  }
+  return true;
+}
+
+/** CSS custom-property name for each checkout-style color token. */
+const CHECKOUT_COLOR_VARS: Record<keyof CheckoutStyleColors, string> = {
+  background: "--tot-checkout-bg",
+  surface: "--tot-checkout-surface",
+  primary: "--tot-checkout-primary",
+  primaryContrast: "--tot-checkout-primary-contrast",
+  accent: "--tot-checkout-accent",
+  text: "--tot-checkout-text",
+};
+
+/**
+ * Serialize a resolved `CheckoutStyle` into a `:root { … }` block of CSS custom
+ * properties (`--tot-checkout-*`) that a FoxyCart checkout template references.
+ * Deterministic (stable key order) so an unchanged style produces byte-identical
+ * output — the publisher can hash it to skip no-op pushes. The `logoUrl`, when
+ * set, is emitted as `--tot-checkout-logo: url("…")`.
+ *
+ * Output is ASCII by construction for the default palette; a merchant-supplied
+ * value (e.g. an exotic font-family or logo URL) could introduce non-ASCII, so
+ * the publisher still validates the final string with `isAsciiSafe` — this
+ * function does not throw, it just serializes.
+ */
+export function checkoutStyleToCss(style: CheckoutStyle): string {
+  const lines: string[] = [];
+  const push = (name: string, value: string) => lines.push(`  ${name}: ${value};`);
+
+  for (const key of Object.keys(CHECKOUT_COLOR_VARS) as (keyof CheckoutStyleColors)[]) {
+    push(CHECKOUT_COLOR_VARS[key], style.colors[key]);
+  }
+  push("--tot-checkout-font-family", style.typography.fontFamily);
+  push("--tot-checkout-font-size", style.typography.baseSize);
+  push("--tot-checkout-button-radius", style.button.radius);
+  if (style.logoUrl) {
+    push("--tot-checkout-logo", `url("${style.logoUrl}")`);
+  }
+
+  return `:root {\n${lines.join("\n")}\n}`;
+}
+
+/**
+ * Assemble the full checkout CSS served at the stable storefront URL that becomes
+ * FoxyCart's `content_url`: the generated token block (`checkoutStyleToCss` over
+ * the resolved `CheckoutStyle`) followed by the tenant's optional raw-CSS override.
+ *
+ * ASCII discipline (Foxy's cache pass is not Unicode-safe → blank checkout): the
+ * raw override is appended ONLY when it is `isAsciiSafe` — a non-ASCII override is
+ * DROPPED here so a bad byte can never blank the live checkout (the authoritative
+ * reject-at-publish gate is U13's promote GateReport; this is defense-in-depth at
+ * serve time). The token block is ASCII for the default palette and any sane
+ * merchant value. Reads both artifacts per env through the versioned spine; never
+ * throws.
+ */
+export async function buildCheckoutStyleCss(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+): Promise<string> {
+  const tokenCss = checkoutStyleToCss(
+    await resolveCheckoutStyle(get, tenantId, env),
+  );
+  const raw = await resolveCheckoutStyleCss(get, tenantId, env);
+  if (raw && isAsciiSafe(raw)) {
+    return `${tokenCss}\n\n${raw}`;
+  }
+  return tokenCss;
+}

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],
+  };
+}