@tokenoftrust/storefront-runner 1.3.2 → 1.3.4-rc.2

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

@@ -26,6 +26,7 @@
  * local loop then simply runs with no hosted signal, same as today.
  */
 import { readEnv } from "@/lib/env";
+import { redactEmailForHint } from "@/lib/privacy/emailHint";
 
 // The CLI's built-in default MCP (packages/cli login.mjs DEFAULT_MCP_URL). When the derived
 // MCP origin equals this, --mcp is redundant noise, so we omit it.
@@ -69,6 +70,7 @@ export async function mintCliSignInCommand(
   tenant: string | null = null,
   deps: { transport?: HttpTransport } = {},
   activityBridge: { token: string; url: string } | null = null,
+  traceId: string | null = null,
 ): Promise<CliSignInCodeResult> {
   const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
   const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
@@ -125,11 +127,21 @@ export async function mintCliSignInCommand(
   }
 
   const mcpFlag = mcpOrigin === PROD_MCP_ORIGIN ? "" : ` --mcp ${mcpOrigin}`;
+  // Display-only recovery hint for a stale one-use code. If redemption fails before
+  // anything is cached locally, `tot login` can still send the developer back to
+  // cockpit with the right address prefilled.
+  const emailHint = redactEmailForHint(email);
+  const emailHintFlag = emailHint ? ` --email-hint ${emailHint}` : "";
   // Piggyback the activity-bridge credential onto the SAME login line — additive
   // flags, ignored by older CLI builds that don't yet recognize them.
   const activityFlags = activityBridge
     ? ` --activity-token ${activityBridge.token} --activity-url ${activityBridge.url}`
     : "";
+  // The invite→terminal→problem trace id, minted once with this sign-in code and
+  // baked into the activity-ingest-token claims. Emitted here too so `tot login`
+  // records it locally — additive, ignored by older CLI builds. The receiver gets
+  // the SAME id from the ingest-token claims, so runtime/activity writes stamp it.
+  const traceFlag = traceId ? ` --trace-id ${traceId}` : "";
   // A single copy → a three-line paste that takes the developer all the way to a running
   // store, no browser, AND leaves `tot` on their PATH so every later command is a bare
   // `tot …` (not `npx @tokenoftrust/cli …`):
@@ -140,11 +152,18 @@ export async function mintCliSignInCommand(
   //
   // The trailing `&&` chains them: each step runs ONLY if the previous succeeded. In
   // particular a stale/burned code (single-use, short-TTL) fails step 2 and stops there
-  // with `login`'s clear "ask for a fresh invite" error — it never falls through to
-  // `start`'s BROWSER sign-in (the surprise we're avoiding).
+  // with `login`'s cockpit recovery step — it never falls through to `start`'s browser
+  // sign-in (the surprise we're avoiding).
+  // The EXACT version this build was cut alongside — `@tokenoftrust/cli@<version>` — baked
+  // in at build time (astro.config Vite define) so the paste installs precisely the CLI this
+  // cockpit expects, never a floating dist-tag the terminal resolves (which can drift behind
+  // the build; that gap shipped stampless installs). `typeof` guard: the define isn't applied
+  // under vitest, where it falls back to the unpinned spec.
+  const cliInstallSpec =
+    typeof __CLI_INSTALL_SPEC__ !== "undefined" ? __CLI_INSTALL_SPEC__ : "@tokenoftrust/cli";
   const command = [
-    `npm i -g @tokenoftrust/cli &&`,
-    `tot login --code ${payload.token}${mcpFlag}${activityFlags} &&`,
+    `npm i -g ${cliInstallSpec} &&`,
+    `tot login --code ${payload.token}${emailHintFlag}${mcpFlag}${traceFlag}${activityFlags} &&`,
     `tot start`,
   ].join("\n");
   return {

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

@@ -1,16 +1,23 @@
 /**
- * Per-vendor "local dev runtime" latest-state — the LIVE half of the
+ * Per-DEVELOPER "local dev runtime" latest-state — the LIVE half of the
  * local→hosted activity bridge (G1). Where activityStore.ts holds a ring buffer
- * of file-SAVE events, this holds ONE record per vendor: the most recent
- * heartbeat the 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.
+ * 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.
+ *
+ * SCOPED PER (tenant, developer email), NOT per tenant: a store can have many
+ * team members, each running their OWN local loop. Keying on the tenant alone
+ * made every teammate's heartbeat collapse into one latest-wins slot, so the
+ * owner saw "connected" whenever ANYONE with access was running `tot dev` —
+ * never their own machine specifically. The key is now
+ * `dev-runtime:<tenant>:<email>`; the POST writes under the HEARTBEATING dev's
+ * verified email, and the GET reads the VIEWER's own — so "connected" means
+ * "YOUR loop", not "someone on this store".
  *
  * Deliberately SEPARATE from the file-activity buffer: a heartbeat is
- * latest-wins state, not an appended event, so it lives under its own
- * `dev-runtime:<tenant>` key and never touches the ring buffer. No file CONTENT
- * is ever stored — `url` is only the local `http://localhost:<port>/<tenant>/`
- * (low-sensitivity, per decision).
+ * latest-wins state, not an appended event, so it lives under its own key and
+ * never touches the ring buffer. No file CONTENT is ever stored — `url` is only
+ * the local `http://localhost:<port>/<tenant>/` (low-sensitivity, per decision).
  *
  * Liveness is computed SERVER-side from `aliveAt` (the ingest-time server clock,
  * NOT the client's `at`) so a skewed local clock can't make a dead loop look
@@ -25,17 +32,62 @@ export interface DevRuntime {
   runnerVersion?: string;
   /** The local store URL — `http://localhost:<port>/<tenant>/`. Clickable in the cockpit. */
   url?: string;
+  /**
+   * The developer's terminal editor command ($VISUAL/$EDITOR), when set — lets the
+   * cockpit suggest the exact "open this file" command (e.g. `code content/home.html`).
+   * Low-sensitivity (a tool name, never a secret); absent when no editor is set.
+   */
+  editor?: string;
+  /**
+   * The developer's project directory (checkout root), when reported — lets the
+   * cockpit show the FULL path to the file to edit so the open command works from
+   * any directory. The dev's own local path (low-sensitivity, like `url`).
+   */
+  cwd?: string;
+  /** OS platform the CLI heartbeat reported (e.g. "darwin", "linux", "win32"). */
+  os?: string;
+  /** OS release/version string the heartbeat reported (e.g. "24.6.0"). */
+  osVersion?: string;
+  /** CPU architecture the heartbeat reported (e.g. "arm64", "x64"). */
+  arch?: string;
+  /**
+   * The invite→terminal→problem TRACE id — minted once when this developer's
+   * sign-in code was issued and carried in the activity-ingest-token claims, so
+   * every heartbeat stamps the SAME id here. Support looks a live session up by
+   * it (readRuntimeByTrace). Not PII; safe to expose in the cockpit view.
+   */
+  traceId?: string;
+  /**
+   * The developer's email, stamped from the ingest-token claims (NOT the request
+   * body) — so support can tie this runtime record to a person by traceId. PII:
+   * the STORE keeps it (the owner's own data), but it is deliberately stripped
+   * from the GET view (toRuntimeView) and must never reach a log/response sink.
+   */
+  email?: string;
   /** Epoch ms of the latest heartbeat, stamped by the SERVER at ingest (skew-proof). */
   aliveAt: number;
 }
 
-/** The runtime as the GET feed exposes it — the stored record plus a computed `live` flag. */
-export interface DevRuntimeView extends DevRuntime {
+/**
+ * The runtime as the GET feed exposes it — the stored record plus a computed
+ * `live` flag, with `email` (PII) omitted. Support reads the raw record by
+ * traceId; the developer's own browser only ever sees the email-free view.
+ */
+export interface DevRuntimeView extends Omit<DevRuntime, "email"> {
   /** True when the last heartbeat landed within LIVE_WINDOW_MS of `now`. */
   live: boolean;
 }
 
 const KEY_PREFIX = "dev-runtime:";
+/**
+ * Secondary index: traceId -> {appDomain, email} (JSON), so support can look a
+ * developer's LIVE session up by the trace id minted at sign-in without scanning.
+ * Stores BOTH components because the record key is now per (tenant, email).
+ * Mirrors the developer+tenant index in activityIngestToken.ts; a KV store has no
+ * GSI, so the smallest correct discovery path is a maintained index key (written
+ * on every heartbeat, cleared on reset). Same TTL as the record.
+ */
+const TRACE_INDEX_PREFIX = "dev-runtime-by-trace:";
 /**
  * How recent the last heartbeat must be to read as "live". The CLI beats every
  * ~10s, so 30s tolerates a couple of missed/slow beats before we call the loop
@@ -52,9 +104,29 @@ const TTL_SECONDS = 3600;
 /** Cap the free-text fields a bridge-token holder can push into KV. */
 const MAX_VERSION_LEN = 64;
 const MAX_URL_LEN = 256;
+/** An editor command may carry flags/a path (e.g. "code --wait") — a touch more room. */
+const MAX_EDITOR_LEN = 128;
+/** A filesystem path to the project root — allow a deep absolute path. */
+const MAX_CWD_LEN = 512;
+/** OS platform / release / arch are short tokens ("darwin", "24.6.0", "arm64"). */
+const MAX_OS_LEN = 64;
+/** RFC-max email length. */
+const MAX_EMAIL_LEN = 320;
+/** A UUID; a touch of headroom for other id shapes. */
+const MAX_TRACE_LEN = 64;
 
-function key(appDomain: string): string {
-  return KEY_PREFIX + appDomain;
+/**
+ * The per-developer record key: `dev-runtime:<tenant>:<email>`. Email is the
+ * session principal (lowercased here for a stable key). An absent email degrades
+ * to a tenant-only suffix — never silently shared, just an unattributed slot the
+ * viewer's own-email read won't match.
+ */
+function key(appDomain: string, email: string | undefined): string {
+  return `${KEY_PREFIX}${appDomain}:${(email ?? "").toLowerCase()}`;
+}
+
+function traceKey(traceId: string): string {
+  return TRACE_INDEX_PREFIX + traceId;
 }
 
 function clip(v: unknown, max: number): string | undefined {
@@ -73,29 +145,72 @@ function localUrl(v: unknown): string | undefined {
   return s && /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/i.test(s) ? s : undefined;
 }
 
+/**
+ * Trusted identity for the runtime record, sourced from the VERIFIED ingest-token
+ * claims (never the request body): the trace id minted at sign-in and the
+ * developer's email. Kept separate from `body` so a token holder can't spoof
+ * either by putting it in the heartbeat payload.
+ */
+export interface RuntimeIdentity {
+  traceId?: string;
+  email?: string;
+}
+
 /**
  * Normalize a raw heartbeat body into a stored DevRuntime — dropping anything
  * that isn't a bounded string and stamping the SERVER's `aliveAt`. Pure +
- * exported so the route's shaping is unit-tested without KV.
+ * exported so the route's shaping is unit-tested without KV. `identity` carries
+ * the trace id + developer email from the ingest-token claims (trusted), stamped
+ * onto the record so support can find a live session by trace and tie it to a
+ * person; body-supplied os/osVersion/arch are whitelisted like the other fields.
  */
 export function shapeRuntime(
-  body: { cliVersion?: unknown; runnerVersion?: unknown; url?: unknown },
+  body: {
+    cliVersion?: unknown;
+    runnerVersion?: unknown;
+    url?: unknown;
+    editor?: unknown;
+    cwd?: unknown;
+    os?: unknown;
+    osVersion?: unknown;
+    arch?: unknown;
+  },
   aliveAt: number,
+  identity: RuntimeIdentity = {},
 ): DevRuntime {
   const rt: DevRuntime = { aliveAt };
   const cliVersion = clip(body.cliVersion, MAX_VERSION_LEN);
   const runnerVersion = clip(body.runnerVersion, MAX_VERSION_LEN);
   const url = localUrl(body.url);
+  const editor = clip(body.editor, MAX_EDITOR_LEN);
+  const cwd = clip(body.cwd, MAX_CWD_LEN);
+  const os = clip(body.os, MAX_OS_LEN);
+  const osVersion = clip(body.osVersion, MAX_OS_LEN);
+  const arch = clip(body.arch, MAX_OS_LEN);
+  const traceId = clip(identity.traceId, MAX_TRACE_LEN);
+  const email = clip(identity.email, MAX_EMAIL_LEN);
   if (cliVersion) rt.cliVersion = cliVersion;
   if (runnerVersion) rt.runnerVersion = runnerVersion;
   if (url) rt.url = url;
+  if (editor) rt.editor = editor;
+  if (cwd) rt.cwd = cwd;
+  if (os) rt.os = os;
+  if (osVersion) rt.osVersion = osVersion;
+  if (arch) rt.arch = arch;
+  if (traceId) rt.traceId = traceId;
+  if (email) rt.email = email;
   return rt;
 }
 
-/** Read the vendor's latest runtime, or null when none/malformed. Never throws. */
-export async function readRuntime(kv: KVNamespace, appDomain: string): Promise<DevRuntime | null> {
+/** Read a developer's latest runtime (their tenant + email), or null when
+ * none/malformed. Never throws. */
+export async function readRuntime(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+): Promise<DevRuntime | null> {
   try {
-    const raw = await kv.get(key(appDomain));
+    const raw = await kv.get(key(appDomain, email));
     if (!raw) return null;
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || typeof parsed.aliveAt !== "number") return null;
@@ -105,16 +220,72 @@ export async function readRuntime(kv: KVNamespace, appDomain: string): Promise<D
   }
 }
 
-/** Overwrite the vendor's runtime with the latest heartbeat (latest-wins, TTL'd). */
+/** Overwrite a developer's runtime with their latest heartbeat (latest-wins, TTL'd),
+ * scoped to (tenant, email). When the record carries a traceId, also (re)write the
+ * by-trace index (storing BOTH tenant + email) so support can resolve
+ * trace -> record without a scan. */
 export async function writeRuntime(
   kv: KVNamespace,
   appDomain: string,
+  email: string | undefined,
   rt: DevRuntime,
 ): Promise<void> {
-  await kv.put(key(appDomain), JSON.stringify(rt), { expirationTtl: TTL_SECONDS });
+  await kv.put(key(appDomain, email), JSON.stringify(rt), { expirationTtl: TTL_SECONDS });
+  if (rt.traceId) {
+    await kv.put(traceKey(rt.traceId), JSON.stringify({ appDomain, email: email ?? "" }), {
+      expirationTtl: TTL_SECONDS,
+    });
+  }
+}
+
+/**
+ * Resolve a developer's live runtime by the trace id minted at sign-in — the
+ * support lookup path. Reads the by-trace index to find the tenant key, then the
+ * record. Returns the RAW record (email included) — a support/internal read, not
+ * the developer-facing GET view. Null when the trace is unknown/expired. Never
+ * throws.
+ */
+export async function readRuntimeByTrace(
+  kv: KVNamespace,
+  traceId: string,
+): Promise<DevRuntime | null> {
+  if (!traceId) return null;
+  const ptr = await kv.get(traceKey(traceId));
+  if (!ptr) return null;
+  // Pointer is JSON {appDomain, email}. A bare-string pointer is a legacy
+  // (pre per-developer) entry with no email to scope by — treat as unresolvable
+  // (it re-establishes on the next heartbeat, well within the 1h TTL).
+  let appDomain: string | undefined;
+  let email: string | undefined;
+  try {
+    const parsed = JSON.parse(ptr);
+    if (parsed && typeof parsed === "object") {
+      appDomain = parsed.appDomain;
+      email = parsed.email;
+    }
+  } catch {
+    return null;
+  }
+  if (!appDomain) return null;
+  return readRuntime(kv, appDomain, email);
+}
+
+/** Delete a developer's runtime record (their tenant + email) — a "true reset" so a
+ * killed loop stops reading as up immediately instead of lingering until the
+ * TTL/live-window expires. Also drops the by-trace index entry for its current trace. */
+export async function clearRuntime(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+): Promise<void> {
+  const existing = await readRuntime(kv, appDomain, email);
+  await kv.delete(key(appDomain, email));
+  if (existing?.traceId) await kv.delete(traceKey(existing.traceId));
 }
 
-/** Attach the computed `live` flag (aliveAt within LIVE_WINDOW_MS of `now`). Pure. */
+/** Attach the computed `live` flag (aliveAt within LIVE_WINDOW_MS of `now`) and
+ * STRIP `email` (PII) — the developer-facing view never carries it. Pure. */
 export function toRuntimeView(rt: DevRuntime, now: number = Date.now()): DevRuntimeView {
-  return { ...rt, live: now - rt.aliveAt <= LIVE_WINDOW_MS };
+  const { email: _email, ...safe } = rt;
+  return { ...safe, live: now - rt.aliveAt <= LIVE_WINDOW_MS };
 }

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

@@ -42,14 +42,15 @@ export function isCacheablePath(pathname: string, params: URLSearchParams): bool
   // the bare `/dashboard` index is a single-segment slug that would otherwise
   // match the editorial-page rule below and be served across viewers.
   if (pathname === "/dashboard" || pathname.startsWith("/dashboard/")) return false;
-  // `/dev` is the authenticated developer surface — per-viewer (it renders the
-  // signed-in developer's own store, email, and gated demo), so like /dashboard
-  // it must never be shared across viewers. It's also the loudest failure if
-  // stale: its styles build to a CONTENT-HASHED asset (/_astro/dev.<hash>.css),
+  // `/cockpit` (formerly `/dev`) is the authenticated developer surface — per-viewer
+  // (it renders the signed-in developer's own store, email, and gated demo), so like
+  // /dashboard it must never be shared across viewers. It's also the loudest failure
+  // if stale: its styles build to a CONTENT-HASHED asset (/_astro/cockpit.<hash>.css),
   // so a cached old HTML keeps pointing at a hash that no longer exists after the
   // next deploy → the stylesheet 404s and the page renders unstyled (its inline
-  // nonce'd <script> tags break the same way). Never cache it.
-  if (pathname === "/dev") return false;
+  // nonce'd <script> tags break the same way). Never cache it. (/dev is kept too —
+  // it 302-redirects to /cockpit, and redirects must not be cached either.)
+  if (pathname === "/cockpit" || pathname === "/dev") return false;
   if (pathname === "/" || pathname === "/search") return true;
   if (pathname.startsWith("/products/")) return true;
   if (pathname.startsWith("/collections/")) return true;

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

@@ -0,0 +1,53 @@
+/**
+ * GET /health — liveness + deploy-identity probe.
+ *
+ * Answered at the very TOP of middleware (src/middleware), before tenant resolution,
+ * the demo/login access gate, the maintenance kill-switch, and the edge cache — so it
+ * reports the running build's identity regardless of Host, unresolved tenant, or a
+ * closed site. That makes it the canonical "what commit is live?" check:
+ *
+ *   curl -s https://<host>/health | jq .sha
+ *
+ * The SHA is baked at BUILD time (astro.config.mjs Vite `define` → __GIT_SHA__). Because
+ * deploy.sh's source guard pins HEAD to origin/<deploySourceBranch> before shipping, a
+ * clean deploy's /health .sha equals the pushed umbrella tip — compare the two to know
+ * whether the latest is out there. Falls back to "unknown" when the build had no git
+ * context (the `typeof` guard also covers vitest, where the define isn't applied).
+ */
+export const HEALTH_PATH = "/health";
+
+export interface HealthPayload {
+  status: "ok";
+  /** Full 40-char commit SHA this build was cut from, or "unknown". */
+  sha: string;
+  /** First 7 chars of `sha` for eyeballing against `git log`, or "unknown". */
+  shortSha: string;
+}
+
+/**
+ * Build the health payload. The build-time SHA is read via a `typeof` guard so this is
+ * safe under vitest (define not applied). `overrides` exists only for tests.
+ *
+ * Deliberately reports only build IDENTITY (the commit) — no build timestamp or other
+ * fingerprint that would leak deploy cadence or make the response non-reproducible.
+ */
+export function healthPayload(overrides?: { sha?: string }): HealthPayload {
+  const sha =
+    overrides?.sha ?? (typeof __GIT_SHA__ !== "undefined" ? __GIT_SHA__ : "unknown");
+  return {
+    status: "ok",
+    sha,
+    shortSha: sha === "unknown" ? "unknown" : sha.slice(0, 7),
+  };
+}
+
+/** 200 JSON `{status,sha,shortSha}`, never cached. */
+export function healthResponse(): Response {
+  return new Response(JSON.stringify(healthPayload()), {
+    status: 200,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}

package/apps/storefront/src/lib/privacy/emailHint.ts

@@ -0,0 +1,33 @@
+const FULL_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const SAFE_HINT_RE = /^[a-z0-9._%+\-]{1,96}@[a-z0-9.-]{1,96}\.[a-z]{2,63}$/i;
+
+function maskPart(part: string): string {
+  if (part.length <= 2) return `${part.slice(0, 1)}...`;
+  return `${part.slice(0, 1)}...${part.slice(-1)}`;
+}
+
+/** Display-only email hint for URLs/log-safe UX. Never returns the full address. */
+export function redactEmailForHint(email: string): string | null {
+  const raw = String(email || "").trim().toLowerCase();
+  const at = raw.indexOf("@");
+  if (at <= 0) return null;
+  const local = raw.slice(0, at);
+  const domain = raw.slice(at + 1);
+  const parts = domain.split(".").filter(Boolean);
+  if (parts.length < 2) return null;
+  const suffix = parts.pop();
+  const registrable = parts.join(".");
+  if (!suffix || !registrable) return null;
+  return `${maskPart(local)}@${maskPart(registrable)}.${suffix}`;
+}
+
+/**
+ * Accept a display hint from a URL/CLI flag. Legacy full-email values are redacted
+ * before display or persistence; malformed values are dropped.
+ */
+export function normalizeEmailHint(input: string | null | undefined): string | null {
+  const raw = String(input || "").trim().toLowerCase();
+  if (!raw || raw.length > 160 || /\s/.test(raw) || !raw.includes("@")) return null;
+  if (FULL_EMAIL_RE.test(raw) && !raw.includes("...")) return redactEmailForHint(raw);
+  return SAFE_HINT_RE.test(raw) ? raw : null;
+}

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

@@ -15,6 +15,7 @@
  * injection is a deliberate string replace — robust for first-party documents, not a
  * sanitizer. Untrusted vendor HTML must be sandboxed/sanitized instead.
  */
+export { rawHtmlPolicy } from "@tot/public-runtime";
 
 /**
  * Marker a body-only page fragment's chrome wrapper uses to say "the page body

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

@@ -10,7 +10,11 @@
  * the source they point a section at — NEVER from forking a component per
  * merchant. That's what keeps a tenant single-tenant-extractable.
  */
-import type { CatalogProduct } from "@tot/public-runtime";
+import {
+  normalizeProductSectionSource,
+  type CatalogProduct,
+  type ProductSectionSource,
+} from "@tot/public-runtime";
 import type { ToTClient } from "@/lib/tot/ToTClient";
 import { isOnSale } from "@/lib/tot/query";
 
@@ -18,16 +22,7 @@ import { isOnSale } from "@/lib/tot/query";
  * Where a merchandising section gets its products. Exactly one shape per source.
  * `handle` placeholders are product/collection handles (unique per tenant).
  */
-export type SectionSource =
-  | { collection: string } // products in a collection (by handle)
-  | { tag: string } // products carrying a tag
-  | { featured: true } // the curated/featured set (getFeatured)
-  | { newest: true } // newest-first
-  | { bestSelling: true } // bestseller-tagged
-  | { onSale: true } // anything with a live compare-at markdown
-  | { handles: string[] } // an explicit, ordered handle list
-  | { related: string } // products related to a base product (by handle)
-  | { recentlyViewed: true }; // client-personalized — resolves empty server-side
+export type SectionSource = ProductSectionSource;
 
 export const DEFAULT_SECTION_LIMIT = 12;
 
@@ -48,51 +43,52 @@ export async function resolveSectionSource(
   tot: ToTClient,
   limit: number = DEFAULT_SECTION_LIMIT,
 ): Promise<CatalogProduct[]> {
-  if ("collection" in source) {
+  const resolved = normalizeProductSectionSource(source);
+  if ("collection" in resolved) {
     const { products } = await tot.listProducts({
-      collection: source.collection,
+      collection: resolved.collection,
       pageSize: limit,
     });
     return products.slice(0, limit);
   }
 
-  if ("featured" in source) {
+  if ("featured" in resolved) {
     return (await tot.getFeatured(limit)).slice(0, limit);
   }
 
-  if ("newest" in source) {
+  if ("newest" in resolved) {
     const { products } = await tot.listProducts({ sort: "newest", pageSize: limit });
     return products.slice(0, limit);
   }
 
-  if ("handles" in source) {
+  if ("handles" in resolved) {
     const found = await Promise.all(
-      source.handles.map((h) => tot.getProductByHandle(h)),
+      resolved.handles.map((h) => tot.getProductByHandle(h)),
     );
     return found
       .filter((p): p is CatalogProduct => !!p && isActive(p))
       .slice(0, limit);
   }
 
-  if ("tag" in source) {
+  if ("tag" in resolved) {
     const all = await tot.getAllActiveProducts();
-    return all.filter((p) => p.tags.includes(source.tag)).slice(0, limit);
+    return all.filter((p) => p.tags.includes(resolved.tag)).slice(0, limit);
   }
 
-  if ("onSale" in source) {
+  if ("onSale" in resolved) {
     const all = await tot.getAllActiveProducts();
     return all.filter(isOnSale).slice(0, limit);
   }
 
-  if ("bestSelling" in source) {
+  if ("bestSelling" in resolved) {
     const all = await tot.getAllActiveProducts();
     return all
       .filter((p) => p.tags.some((t) => BESTSELLER_TAGS.has(t)))
       .slice(0, limit);
   }
 
-  if ("related" in source) {
-    const base = await tot.getProductByHandle(source.related);
+  if ("related" in resolved) {
+    const base = await tot.getProductByHandle(resolved.related);
     if (!base) return [];
     const baseCollections = new Set(base.collections);
     const baseTags = new Set(base.tags);

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

@@ -17,7 +17,7 @@ export const SECURITY_HEADERS: Readonly<Record<string, string>> = {
   "X-Frame-Options": "SAMEORIGIN",
   "Referrer-Policy": "strict-origin-when-cross-origin",
   // Lock powerful features off for the browse storefront. Verification and
-  // checkout (Powered by FoxyCart) run in their own surfaces that grant only
+  // checkout run in their own surfaces that grant only
   // what they need via per-frame Permissions-Policy.
   "Permissions-Policy":
     "camera=(), microphone=(), geolocation=(), browsing-topics=(), interest-cohort=()",

package/apps/storefront/src/lib/storyblok/content-model.ts

@@ -8,6 +8,7 @@
  * pilot CHILD space holds the content instances. See DECISIONS.md for the
  * parent/child + Shared Components plan.
  */
+import type { ProductSectionSource } from "@tot/public-runtime";
 
 export type HomeBlock =
   | HeroBlock
@@ -52,8 +53,8 @@ export interface FeaturedCollectionsBlock {
 export interface FeaturedProductsBlock {
   component: "featured_products";
   title?: string;
-  /** "featured" | "newest" | explicit handles. */
-  source: "featured" | "newest";
+  /** Public merchandising source contract. Omit for featured; legacy handles still work. */
+  source?: ProductSectionSource;
   handles?: string[];
   limit?: number;
 }