@tokenoftrust/storefront-runner 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "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/scripts/lib/tenant-dirs.mjs

@@ -0,0 +1,80 @@
+/**
+ * Where a tenant's colocated directory lives — the NODE-side copy.
+ *
+ * A tenant IS a directory. Real tenants sit directly under `tenants/<id>/`;
+ * PLATFORM TEST tenants (every id ending `.e2e.test`) sit one level deeper,
+ * under `tenants/e2e/<id>/`.
+ *
+ * `@tot/public-runtime` owns this contract for the Worker/TS side
+ * (`packages/public-runtime/src/tenant.ts`), but it is TypeScript source with no
+ * build output, so the `.mjs` build/dev/tenant scripts cannot import it. This is
+ * that same total mapping, byte-for-byte in behavior, and
+ * `packages/public-runtime/tests/tenant-dirs-parity.test.ts` fails the build if
+ * the two ever disagree on any id.
+ */
+
+/** The directory segment platform test tenants are nested under. */
+export const E2E_TENANT_DIR = "e2e";
+
+/** True for a PLATFORM TEST tenant id — the `<scenario>.e2e.test` class. */
+export function isE2ETenantId(tenantId) {
+  return /\.e2e\.test$/.test(tenantId);
+}
+
+/** Repo-relative, POSIX-separated directory for a tenant id. */
+export function tenantDirRelative(tenantId) {
+  return isE2ETenantId(tenantId)
+    ? `tenants/${E2E_TENANT_DIR}/${tenantId}`
+    : `tenants/${tenantId}`;
+}
+
+/** The `/tenants/…/<id>/` substring identifying one tenant inside a path. */
+export function tenantDirSegment(tenantId) {
+  return `/${tenantDirRelative(tenantId)}/`;
+}
+
+/** The tenant id a `…/tenants/[e2e/]<id>/…` path encodes, or null. */
+export function tenantIdFromPath(path) {
+  return /\/tenants\/(?:e2e\/)?([^/]+)\//.exec(path)?.[1] ?? null;
+}
+
+/**
+ * Narrow a set of tenant ids to what a generalized listing should show —
+ * platform test tenants are dropped unless explicitly requested.
+ */
+export function listedTenantIds(ids, opts = {}) {
+  return opts.includeTestTenants ? [...ids] : ids.filter((id) => !isE2ETenantId(id));
+}
+
+/**
+ * Path segments (relative to the repo root) for a tenant's own directory —
+ * ready for `join(repoRoot, ...tenantDirSegments(id))`.
+ */
+export function tenantDirSegments(tenantId) {
+  return tenantDirRelative(tenantId).split("/");
+}
+
+/**
+ * Every tenant id with a directory under `tenants/`, real and test, from one
+ * `readdir`-shaped view of the tree. `readdirSync` is passed in so the walk
+ * stays testable without a filesystem.
+ *
+ * @param tenantsDir absolute path to the repo's `tenants/` directory
+ * @param readdir    `(dir) => string[]` listing a directory's entry names
+ * @param isDir      `(path) => boolean`
+ * @param join       path join
+ */
+export function listTenantDirIds(tenantsDir, readdir, isDir, join) {
+  const ids = [];
+  for (const entry of readdir(tenantsDir)) {
+    if (!isDir(join(tenantsDir, entry))) continue;
+    if (entry === E2E_TENANT_DIR) {
+      for (const nested of readdir(join(tenantsDir, entry))) {
+        if (isDir(join(tenantsDir, entry, nested))) ids.push(nested);
+      }
+      continue;
+    }
+    ids.push(entry);
+  }
+  return ids;
+}

package/scripts/tenant/lint-embeds.mjs

@@ -0,0 +1,180 @@
+/**
+ * Dev-loop lint for third-party embeds (shift-left for the CSP allowlist).
+ *
+ * A strict CSP silently blocks any external <script>/<iframe> a tenant page
+ * embeds unless the origin is allowlisted (see packages/public-runtime/src/csp.ts
+ * — EMBED_PROVIDERS + embedCspAdditions). A blocked embed produces no build
+ * error and no page error — just a blank spot — so historically the only way it
+ * surfaced was a human noticing and escalating to the platform team.
+ *
+ * This lint closes that gap at author/preview time: it scans a tenant's HTML for
+ * external embed origins and tells the developer, right where they're working:
+ *   - KNOWN provider present  → make sure the tenant opts the slug into `embeds`
+ *     (if we know the opt-in, hard-fail when it's missing).
+ *   - UNKNOWN external origin  → it will be blocked; a platform catalog entry is
+ *     needed (EMBED_PROVIDERS), not a raw-origin config edit.
+ *
+ * Source of truth for the catalog is EMBED_PROVIDERS in TS; KNOWN_EMBEDS below
+ * mirrors it for dependency-free `node` execution and a vitest parity test
+ * (lint-embeds.test.mjs) fails if the two drift.
+ *
+ * Usage:
+ *   node scripts/tenant/lint-embeds.mjs --dir tenants/<id>/content [--declared pipedrive,calendly]
+ *   node scripts/tenant/lint-embeds.mjs --dir <tenant-repo>/content
+ * Exit non-zero when a blocking finding exists (undeclared known provider given
+ * a known opt-in, or an unknown external origin) so `tot preview` / CI can gate.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+import { EMBED_PROVIDERS } from "../../packages/public-runtime/src/embed-catalog.mjs";
+
+/**
+ * The embed catalog, flattened for the lint from the shared source of truth
+ * (packages/public-runtime/src/embed-catalog.mjs — imported directly, no mirror).
+ * `markers` = substrings meaning the embed is on a page; `origins` = the union
+ * of the provider's exact CSP hosts.
+ */
+export const KNOWN_EMBEDS = Object.entries(EMBED_PROVIDERS).map(([slug, p]) => ({
+  slug,
+  label: p.label,
+  markers: p.markers,
+  origins: [...new Set([...(p.scriptSrc ?? []), ...(p.connectSrc ?? []), ...(p.frameSrc ?? [])])],
+}));
+
+/** Hosts the platform always allows (self is implicit); embeds to these are fine. */
+const ALWAYS_ALLOWED_HOSTS = new Set([
+  "static.cloudflareinsights.com",
+  "cloudflareinsights.com",
+]);
+
+// Only <script src> and <iframe src> load executable/frameable content the CSP
+// gates (script-src / frame-src). We deliberately DON'T scan generic URLs
+// (canonical links, JSON-LD @context, <a href>, og:url) — those aren't embeds
+// and would be noisy false positives. Provider-specific embeds that mount via a
+// data-attribute (e.g. Pipedrive's data-pd-webforms) are caught by their catalog
+// marker instead, so they're covered without a generic URL sweep.
+const SRC_RE = /<(?:script|iframe)\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi;
+
+/** Origin (host) of an absolute URL, or null for relative/self URLs. */
+function originOf(u) {
+  try {
+    return new URL(u).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify one HTML document's embeds.
+ * @returns {{ knownSlugs: string[], externalOrigins: string[], unknownOrigins: string[] }}
+ */
+export function scanHtmlForEmbeds(html) {
+  const knownSlugs = new Set();
+  for (const { slug, markers } of KNOWN_EMBEDS) {
+    if (markers.some((m) => html.includes(m))) knownSlugs.add(slug);
+  }
+  const external = new Set();
+  SRC_RE.lastIndex = 0;
+  let m;
+  while ((m = SRC_RE.exec(html))) {
+    const origin = originOf(m[1]);
+    if (!origin) continue;
+    const host = new URL(origin).hostname;
+    if (ALWAYS_ALLOWED_HOSTS.has(host)) continue;
+    external.add(origin);
+  }
+  // An external origin is "unknown" if no catalog provider claims it.
+  const catalogOrigins = new Set(KNOWN_EMBEDS.flatMap((p) => p.origins));
+  const unknown = [...external].filter((o) => !catalogOrigins.has(o));
+  return {
+    knownSlugs: [...knownSlugs],
+    externalOrigins: [...external],
+    unknownOrigins: unknown,
+  };
+}
+
+function walkHtml(dir) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walkHtml(p));
+    else if (extname(p) === ".html") out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Lint every HTML file under `dir`.
+ * @param {{ dir: string, declared?: string[] | null }} opts
+ *   `declared` = the tenant's opted-in slugs if known (platform CI); when null,
+ *   findings for known providers are advisory (we can't prove the opt-in here).
+ * @returns {{ findings: Array<{level:'error'|'warn'|'info', file:string, message:string}>, blocking: boolean }}
+ */
+export function lintTenantEmbeds({ dir, declared = null }) {
+  /** @type {Array<{level:'error'|'warn'|'info', file:string, message:string}>} */
+  const findings = [];
+  const declaredSet = declared ? new Set(declared) : null;
+  for (const file of walkHtml(dir)) {
+    const html = readFileSync(file, "utf8");
+    const { knownSlugs, unknownOrigins } = scanHtmlForEmbeds(html);
+    for (const slug of knownSlugs) {
+      const label = KNOWN_EMBEDS.find((p) => p.slug === slug)?.label ?? slug;
+      if (declaredSet && !declaredSet.has(slug)) {
+        findings.push({
+          level: "error",
+          file,
+          message: `embeds ${label} but the tenant has not opted "${slug}" into its embeds allowlist — the CSP will block it. Add "${slug}" to the tenant's embeds config.`,
+        });
+      } else if (!declaredSet) {
+        findings.push({
+          level: "info",
+          file,
+          message: `embeds ${label}: ensure "${slug}" is in the tenant's embeds allowlist, or the CSP will block it.`,
+        });
+      }
+    }
+    for (const origin of unknownOrigins) {
+      findings.push({
+        level: "error",
+        file,
+        message: `embeds ${origin}, which is not a known embed provider — the CSP will block it. A platform catalog entry (EMBED_PROVIDERS) is required, or remove the embed.`,
+      });
+    }
+  }
+  return { findings, blocking: findings.some((f) => f.level === "error") };
+}
+
+function parseArgs(argv) {
+  const args = { dir: null, declared: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--dir") args.dir = argv[++i];
+    else if (argv[i] === "--declared") args.declared = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return args;
+}
+
+function main() {
+  const { dir, declared } = parseArgs(process.argv.slice(2));
+  if (!dir) {
+    console.error("usage: node scripts/tenant/lint-embeds.mjs --dir <content-dir> [--declared slug,slug]");
+    process.exit(2);
+  }
+  const { findings, blocking } = lintTenantEmbeds({ dir, declared });
+  if (findings.length === 0) {
+    console.log("embed lint: no external embeds found (or all allowlisted).");
+    return;
+  }
+  for (const f of findings) {
+    const tag = f.level === "error" ? "BLOCKED" : f.level === "warn" ? "WARN" : "note";
+    console.log(`[embed-lint:${tag}] ${f.file}\n    ${f.message}`);
+  }
+  if (blocking) {
+    console.error(`\nembed lint: ${findings.filter((f) => f.level === "error").length} embed(s) will be blocked by CSP — see above.`);
+    process.exit(1);
+  }
+}
+
+// Only run main when invoked directly, not when imported by the parity test.
+if (import.meta.url === `file://${process.argv[1]}`) main();