@tokenoftrust/storefront-runner 2.2.95 → 2.2.97

package/agency-kit/tools/lib/embed-catalog.mjs

@@ -0,0 +1,99 @@
+/**
+ * The reviewed third-party embed catalog: the providers a store may opt into, and the exact
+ * origins each one needs. The one copy: the platform's CSP, its reconcile frame check, the
+ * static-publish CSP pipeline, the dev-loop lint and the kit's own tools all read it (the platform
+ * re-exports this module).
+ *
+ * Pure and dependency-free, so plain `node` tooling and the Worker both import it.
+ *
+ * A store opts in by slug: `embeds` in its `.tot/config.json` (or its `embeds.json`). Each entry:
+ * `markers` are substrings that appear in rendered HTML when the embed is on a page (so CSP origins
+ * are added only to pages that use it); `frameSrc`/`connectSrc`/`scriptSrc` are the EXACT origins
+ * the embed needs in the parent document, never wildcards. The embed renders in a cross-origin
+ * iframe governed by the provider's own CSP.
+ *
+ * @type {Readonly<Record<string, {
+ *   label: string, markers: readonly string[], scriptSrc?: readonly string[],
+ *   connectSrc?: readonly string[], frameSrc?: readonly string[] }>>}
+ */
+export const EMBED_PROVIDERS = {
+  pipedrive: {
+    label: "Pipedrive Web Forms",
+    // The embed div carries data-pd-webforms=… and the loader is
+    // webforms.pipedrive.com/f/loader; either marker means the form is present.
+    markers: ["webforms.pipedrive.com", "pipedriveWebForms"],
+    // The nonce-allowed loader fetches its form definition from this origin and
+    // mounts the form in a same-origin iframe from it. script-src as a
+    // belt-and-suspenders in case a future loader drops the parent-tag nonce.
+    scriptSrc: ["https://webforms.pipedrive.com"],
+    connectSrc: ["https://webforms.pipedrive.com"],
+    frameSrc: ["https://webforms.pipedrive.com"],
+  },
+  youtube: {
+    label: "YouTube video (privacy-enhanced)",
+    // Only the privacy-enhanced player: it sets no tracking cookies until the visitor plays the
+    // video. A www.youtube.com/embed/ iframe is rewritten to it (tools/video-embeds.mjs).
+    markers: ["www.youtube-nocookie.com/embed/"],
+    frameSrc: ["https://www.youtube-nocookie.com"],
+  },
+  vimeo: {
+    label: "Vimeo video",
+    markers: ["player.vimeo.com/video/"],
+    frameSrc: ["https://player.vimeo.com"],
+  },
+};
+
+/**
+ * Every frame origin the given opted-in slugs allow (unknown slugs allow nothing).
+ * @param {readonly string[] | null | undefined} slugs
+ * @returns {string[]}
+ */
+export function embedFrameOrigins(slugs) {
+  /** @type {Set<string>} */
+  const out = new Set();
+  for (const slug of slugs ?? []) {
+    for (const origin of EMBED_PROVIDERS[slug]?.frameSrc ?? []) out.add(origin);
+  }
+  return [...out];
+}
+
+/**
+ * The catalog slug whose `frameSrc` includes `origin`, or null.
+ * @param {string} origin
+ * @returns {string | null}
+ */
+export function embedSlugForFrameOrigin(origin) {
+  for (const [slug, provider] of Object.entries(EMBED_PROVIDERS)) {
+    if (provider.frameSrc?.includes(origin)) return slug;
+  }
+  return null;
+}
+
+// A tag's `src`, in HTML or in HTML held in a JSON string (where its quotes are escaped).
+const IFRAME_TAG_RE = /<iframe\b[^>]*>/gi;
+const SRC_ATTR_RE = /\bsrc\s*=\s*\\?["']([^"'\\]+)/i;
+
+/**
+ * Every `<iframe>` in a text (HTML, or JSON holding HTML), with the origin of its `src` (null when
+ * it has none or it is not an absolute URL).
+ *
+ * @param {string} text
+ * @returns {Array<{ tag: string, src: string | null, origin: string | null }>}
+ */
+export function findIframes(text) {
+  /** @type {Array<{ tag: string, src: string | null, origin: string | null }>} */
+  const out = [];
+  for (const [tag] of String(text).matchAll(IFRAME_TAG_RE)) {
+    const src = SRC_ATTR_RE.exec(tag)?.[1] ?? null;
+    let origin = null;
+    if (src) {
+      try {
+        origin = new URL(src).origin;
+      } catch {
+        origin = null;
+      }
+    }
+    out.push({ tag, src, origin });
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.95",
+  "version": "2.2.97",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/declared-config.mjs

@@ -11,7 +11,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "siteType", "compliance", "capabilities", "features",
+  "siteType", "compliance", "capabilities", "features", "embeds",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -74,5 +74,9 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
   if (config.capabilities !== undefined && !isObject(config.capabilities)) {
     out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
   }
+  if (config.embeds !== undefined
+    && !(Array.isArray(config.embeds) && config.embeds.every((/** @type {unknown} */ s) => typeof s === "string"))) {
+    out.push(mk(ERROR, "config-embeds", file, '`embeds` must be an array of embed slugs, e.g. ["youtube"]'));
+  }
   return out;
 }

package/packages/cli/src/tot-repo-mappings.mjs

@@ -0,0 +1,153 @@
+/**
+ * `.tot/config.json` mapping resolution — the ONE reading of a store repo's
+ * declared layout, shared by every consumer: the hosted reconcile (preview,
+ * candidate, aggregate, publication), `tot dev`'s checkout graft, `tot validate`,
+ * the platform's materialize / asset-repair scripts, and this kit's
+ * `repair-tenant-config.mjs`. The platform imports this file from the kit.
+ *
+ * A mapping is `{ workspace, repo, kind }`:
+ *   - `workspace` — where the files physically live in the store repo. It is the
+ *     only source of truth for location; nothing assumes a `tenants/<id>/` layout
+ *     inside the store's own repo.
+ *   - `repo` — the storefront artifact target, `tenants/<segment>/<rel>`. Only
+ *     `<rel>` (the tenant-relative path: `theme.json`, `content/`, `public/`, …)
+ *     is read from it. The tenant namespace always comes from the CANONICAL
+ *     tenant id — the store's registered id hosted, the config's `tenant` locally
+ *     — never from `<segment>`, so a config whose segment disagrees with its
+ *     tenant id resolves identically on every surface.
+ *
+ * Pure and dependency-free so kit tools, platform `.mjs` scripts and TypeScript
+ * consumers (types in the adjacent `.d.mts`) all import it. The published CLI
+ * installs without the kit, so it ships a byte-identical copy that its own test
+ * suite holds equal to this file.
+ */
+
+/** Platform test tenants nest one level deeper: `tenants/e2e/<id>.e2e.test/`. */
+const TARGET_RE = /^tenants\/(?:e2e\/([^/]+\.e2e\.test)|([^/]+))(?:\/(.*))?$/;
+
+/**
+ * Split a declared mapping target into the tenant segment it names and the
+ * tenant-relative path it addresses. Null when the target is not under
+ * `tenants/<segment>/`, or when its relative part is not a clean path (empty,
+ * `.` or `..` segments) — such a target could address outside the tenant.
+ * A trailing `/` (tree target) is preserved on `rel`; the tenant root is `""`.
+ * @param {unknown} repo
+ * @returns {{ segment: string, rel: string } | null}
+ */
+export function parseMappingTarget(repo) {
+  if (typeof repo !== "string") return null;
+  const m = TARGET_RE.exec(repo);
+  if (!m) return null;
+  const segment = m[1] ?? m[2];
+  const rel = m[3] ?? "";
+  const parts = rel.replace(/\/$/, "").split("/");
+  if (rel && parts.some((p) => !p || p === "." || p === "..")) return null;
+  return { segment, rel };
+}
+
+/** The canonical artifact root for a tenant: `tenants/<tenantId>/`. */
+export function tenantArtifactRoot(tenantId) {
+  return `tenants/${tenantId}/`;
+}
+
+function asDir(path) {
+  return path === "" || path.endsWith("/") ? path : `${path}/`;
+}
+
+function mappingsOf(config) {
+  return Array.isArray(config?.mappings) ? config.mappings : [];
+}
+
+/**
+ * Map a tenant-repo path to its tenant-relative path (e.g. `content/home.json`).
+ * First match wins; a `file` mapping matches exactly, a `tree` mapping by prefix.
+ * Null when no mapping covers the path or the covering mapping's target is not
+ * a valid tenant target.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToTenantRelative(config, workspacePath) {
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    if (m.kind === "file") {
+      if (workspacePath !== m.workspace) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? target.rel : null;
+    }
+    if (m.kind === "tree") {
+      const ws = asDir(m.workspace);
+      if (!workspacePath.startsWith(ws)) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? asDir(target.rel) + workspacePath.slice(ws.length) : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Map a tenant-repo path to its storefront artifact path under the CANONICAL
+ * tenant root (`tenants/<tenantId>/<rel>`). Null when unmapped.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToArtifact(config, tenantId, workspacePath) {
+  const rel = mapWorkspaceToTenantRelative(config, workspacePath);
+  return rel === null ? null : tenantArtifactRoot(tenantId) + rel;
+}
+
+/**
+ * The inverse: where a tenant-relative path (`theme.json`, `content`, `public`,
+ * `content/home.json`) lives in the tenant repo, per the declared mappings.
+ * Unmapped paths resolve to themselves — the flat checkout layout — so a
+ * consumer still finds files the mappings do not cover (and the config-coverage
+ * check reports the gap).
+ * @param {{ mappings?: unknown }} config
+ * @param {string} relPath tenant-relative, no leading `/`
+ * @returns {string}
+ */
+export function workspacePathForTenantRelative(config, relPath) {
+  const bare = relPath.replace(/\/$/, "");
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    const target = parseMappingTarget(m.repo);
+    if (!target) continue;
+    const targetRel = target.rel.replace(/\/$/, "");
+    const ws = m.workspace.replace(/\/$/, "");
+    if (m.kind === "file") {
+      if (targetRel === bare) return ws;
+      continue;
+    }
+    if (m.kind !== "tree") continue;
+    if (targetRel === bare) return ws;
+    const prefix = asDir(targetRel);
+    if (bare.startsWith(prefix)) {
+      const rest = bare.slice(prefix.length);
+      return ws ? `${ws}/${rest}` : rest;
+    }
+  }
+  return bare;
+}
+
+/**
+ * Mappings whose declared target names a tenant segment other than the
+ * canonical tenant id. They still resolve correctly (the segment is never
+ * read); this exists so validators can tell the author the config disagrees
+ * with itself.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @returns {{ workspace: string, repo: string, segment: string }[]}
+ */
+export function foreignTenantSegments(config, tenantId) {
+  const out = [];
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object") continue;
+    const target = parseMappingTarget(m.repo);
+    if (target && target.segment !== tenantId) {
+      out.push({ workspace: String(m.workspace ?? ""), repo: m.repo, segment: target.segment });
+    }
+  }
+  return out;
+}

package/packages/cli/src/visual-parity.mjs

@@ -1,11 +1,13 @@
 /**
  * Read-only closure checks for the optional visual-parity migration module.
- * The tenant checkout remains portable: this reads only content/, public/, and
- * .tot/visual-parity.json, never a preview host or a delivery provider.
+ * The tenant checkout remains portable: this reads only content/, public/ and theme.json (where
+ * `.tot/config.json` maps them) and .tot/visual-parity.json, never a preview host or a delivery
+ * provider.
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { extname, join, relative } from "node:path";
+import { workspacePathForTenantRelative } from "./tot-repo-mappings.mjs";
 
 const ERROR = "error";
 // Public routes implemented by the renderer. Authentication and cart URLs are
@@ -59,10 +61,10 @@ function parseConfig(tenantDir) {
   }
 }
 
-function tenantFromConfig(tenantDir) {
+/** The checkout's `.tot/config.json`, or null when absent or unreadable. */
+function readTotConfig(tenantDir) {
   try {
-    const value = JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
-    return typeof value?.tenant === "string" ? value.tenant : null;
+    return JSON.parse(readFileSync(join(tenantDir, ".tot", "config.json"), "utf8"));
   } catch { return null; }
 }
 
@@ -278,7 +280,11 @@ export function validateVisualParityClosure(tenantDir, options = {}) {
   const findings = [];
   const { value: config, findings: configFindings } = parseConfig(tenantDir);
   findings.push(...configFindings);
-  const pagesDir = join(tenantDir, "content", "pages");
+  // Files are found where the checkout's `.tot/config.json` mappings declare them, as `tot validate`
+  // and the hosted reconcile find them.
+  const totConfig = readTotConfig(tenantDir);
+  const located = (rel) => join(tenantDir, workspacePathForTenantRelative(totConfig, rel));
+  const pagesDir = located("content/pages");
   const files = walk(pagesDir).filter((file) => file.endsWith(".json")).sort();
   if (files.length === 0) findings.push(finding("parity-pages-missing", "content/pages/", "no page JSON files define the visual-parity route scope", "add the paired authored page records under content/pages/ before closing parity"));
   const pages = [];
@@ -297,17 +303,17 @@ export function validateVisualParityClosure(tenantDir, options = {}) {
   const routes = new Set(["/"]);
   for (const page of pages) routes.add(normalizeRoute(page.value.slug));
   /** @type {{findings:ParityFinding[], tenantId:string|null, publicDir:string, routes:Set<string>, allowlist:string[], decodeAssets:DecodeAsset[]}} */
-  const context = { findings, tenantId: tenantId ?? tenantFromConfig(tenantDir), publicDir: join(tenantDir, "public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
+  const context = { findings, tenantId: tenantId ?? (typeof totConfig?.tenant === "string" ? totConfig.tenant : null), publicDir: located("public"), routes, allowlist: Array.isArray(config.externalNavigationAllowlist) ? config.externalNavigationAllowlist : [], decodeAssets: [] };
   if (!context.tenantId) findings.push(finding("parity-tenant-id", ".tot/config.json", "tenant id is required to verify /tenants/<tenant>/ assets", "set tenant in .tot/config.json or pass a resolved tenant id"));
   for (const page of pages) inspectValue(page.value, page.file, [], context);
   for (const name of ["home.json", "chrome.json"]) {
-    const path = join(tenantDir, "content", name);
+    const path = located(`content/${name}`);
     if (existsSync(path)) {
       const value = readStructured(path, `content/${name}`, findings);
       if (value != null) inspectValue(value, `content/${name}`, [], context);
     }
   }
-  const themePath = join(tenantDir, "theme.json");
+  const themePath = located("theme.json");
   if (existsSync(themePath)) {
     const value = readStructured(themePath, "theme.json", findings);
     if (value != null) inspectValue(value, "theme.json", [], context);

package/packages/public-runtime/package.json

@@ -18,6 +18,7 @@
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
     "./catalog-files": "./src/catalog-files.ts",
+    "./embed-catalog": "./src/embed-catalog.mjs",
     "./retention-holds": "./src/retention-holds.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./declared-tenant-config": "./src/declared-tenant-config.mjs",

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -1,7 +1,7 @@
 /** Types for the dependency-free declared-tenant-config module (declared-tenant-config.mjs). */
 import type { TenantConfig } from "./tenant.js";
 
-export type DeclaredTenantConfigField = "siteType" | "compliance" | "capabilities" | "features";
+export type DeclaredTenantConfigField = "siteType" | "compliance" | "capabilities" | "features" | "embeds";
 export type DeclaredTenantConfig = Partial<Pick<TenantConfig, DeclaredTenantConfigField>>;
 
 export const DECLARED_TENANT_CONFIG_FIELDS: readonly DeclaredTenantConfigField[];

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -23,6 +23,7 @@ export const DECLARED_TENANT_CONFIG_FIELDS = Object.freeze([
   "compliance",
   "capabilities",
   "features",
+  "embeds",
 ]);
 
 /**
@@ -86,11 +87,12 @@ export function declaredTenantConfig(config) {
   /** @type {Record<string, unknown>} */
   const out = {};
   if (!isPlainObject(config)) return out;
-  const { siteType, compliance, capabilities, features } = /** @type {Record<string, unknown>} */ (config);
+  const { siteType, compliance, capabilities, features, embeds } = /** @type {Record<string, unknown>} */ (config);
   if (typeof siteType === "string" && SITE_TYPES.has(siteType)) out.siteType = siteType;
   if (isPlainObject(compliance)) out.compliance = compliance;
   if (isPlainObject(capabilities)) out.capabilities = capabilities;
   if (isPlainObject(features)) out.features = features;
+  if (Array.isArray(embeds) && embeds.every((slug) => typeof slug === "string")) out.embeds = embeds;
   return out;
 }
 
@@ -101,8 +103,9 @@ export function isEmptyDeclaredTenantConfig(declared) {
 
 /**
  * Overlay a declaration onto a resolved tenant. `siteType` is replaced; the object
- * fields merge key by key, so a declaration adds to — and can set individual keys
- * of — what the platform record already carries, but never erases a key it omits.
+ * fields merge key by key, and `embeds` (catalog slugs) is unioned, so a declaration
+ * adds to — and can set individual keys of — what the platform record already
+ * carries, but never erases what it omits.
  *
  * @template T
  * @param {T} tenant
@@ -115,9 +118,12 @@ export function applyDeclaredTenantConfig(tenant, declared) {
   for (const field of DECLARED_TENANT_CONFIG_FIELDS) {
     const value = declared[field];
     if (value === undefined) continue;
-    out[field] = isPlainObject(value) && isPlainObject(out[field])
-      ? { ...out[field], ...value }
-      : value;
+    const current = out[field];
+    out[field] = isPlainObject(value) && isPlainObject(current)
+      ? { ...current, ...value }
+      : Array.isArray(value) && Array.isArray(current)
+        ? [...new Set([...current, ...value])]
+        : value;
   }
   return /** @type {T} */ (out);
 }

package/packages/public-runtime/src/embed-catalog.d.mts

@@ -1,9 +1,2 @@
-/** Types for the dependency-free embed catalog data module (embed-catalog.mjs). */
-export interface EmbedProviderData {
-  label: string;
-  markers: readonly string[];
-  scriptSrc?: readonly string[];
-  connectSrc?: readonly string[];
-  frameSrc?: readonly string[];
-}
-export const EMBED_PROVIDERS: Readonly<Record<string, EmbedProviderData>>;
+/** Types for the reviewed embed catalog (agency-kit/tools/lib/embed-catalog.mjs), re-exported here. */
+export * from "../../../agency-kit/tools/lib/embed-catalog.mjs";

package/packages/public-runtime/src/embed-catalog.mjs

@@ -1,40 +1,5 @@
-/**
- * Single source of truth for the third-party embed catalog (CSP allowlist).
- *
- * Plain JS ON PURPOSE: this data is consumed both by TypeScript (csp.ts, the
- * worker runtime) AND by plain-`node` tooling that can't import TS — the
- * dev-loop lint (scripts/tenant/lint-embeds.mjs) runs under `node --test` /
- * `node`. Keeping the catalog here, dependency-free, lets those share ONE copy
- * instead of hand-mirroring it. (The published `tot` CLI validator keeps its own
- * inline copy — it can't reach this package at runtime — but a parity test
- * pins it to this module so it can't drift.)
- *
- * Each entry: `markers` are substrings that appear in rendered HTML when the
- * embed is present on a page (so the CSP origins are added only to pages that
- * actually use it); `frameSrc`/`connectSrc`/`scriptSrc` are the EXACT hosts the
- * embed needs in the parent document — never wildcards. The embed itself renders
- * in a cross-origin iframe governed by the provider's own CSP.
- *
- * @typedef {Object} EmbedProviderData
- * @property {string} label
- * @property {readonly string[]} markers
- * @property {readonly string[]} [scriptSrc]
- * @property {readonly string[]} [connectSrc]
- * @property {readonly string[]} [frameSrc]
- *
- * @type {Readonly<Record<string, EmbedProviderData>>}
- */
-export const EMBED_PROVIDERS = {
-  pipedrive: {
-    label: "Pipedrive Web Forms",
-    // The embed div carries data-pd-webforms=… and the loader is
-    // webforms.pipedrive.com/f/loader; either marker means the form is present.
-    markers: ["webforms.pipedrive.com", "pipedriveWebForms"],
-    // The nonce-allowed loader fetches its form definition from this origin and
-    // mounts the form in a same-origin iframe from it. script-src as a
-    // belt-and-suspenders in case a future loader drops the parent-tag nonce.
-    scriptSrc: ["https://webforms.pipedrive.com"],
-    connectSrc: ["https://webforms.pipedrive.com"],
-    frameSrc: ["https://webforms.pipedrive.com"],
-  },
-};
+// @ts-check
+// The reviewed embed catalog is the agency kit's pure module, so a store developer checks an embed
+// with the kit alone and the platform enforces the same entries. This subpath is how the platform
+// imports it.
+export * from "../../../agency-kit/tools/lib/embed-catalog.mjs";

package/scripts/tenant/validate.mjs

@@ -1241,10 +1241,11 @@ export function validateTenant(tenantDir, opts = {}) {
   // spot a human has to notice. Advisory (info) when there's no embeds.json to
   // compare against, since the opt-in may be the platform build-time default.
   if (existsSync(contentDir)) {
-    let declaredEmbeds = null;
+    // The opt-in is the `embeds` .tot/config.json declares, plus an embeds.json.
+    let declaredEmbeds = Array.isArray(config?.embeds) ? config.embeds.filter((s) => typeof s === "string") : null;
     if (existsSync(embedsPath)) {
       const { value } = readJsonSafe(embedsPath);
-      if (Array.isArray(value)) declaredEmbeds = value.filter((s) => typeof s === "string");
+      if (Array.isArray(value)) declaredEmbeds = [...(declaredEmbeds ?? []), ...value.filter((s) => typeof s === "string")];
     }
     for (const f of lintTenantEmbeds({ dir: contentDir, declared: declaredEmbeds }).findings) {
       findings.push(mk(f.level, "embed-csp", rel(f.file), f.message));