@tokenoftrust/storefront-runner 2.0.2 → 2.0.4

package/apps/storefront/src/lib/shared/invitePreflight.ts

@@ -0,0 +1,123 @@
+/**
+ * Invite preflight — block a developer invite when the target store's repo isn't
+ * provisioned on THIS environment, so a broken connection surfaces to the INVITER
+ * at invite time instead of dead-ending later in the invitee's terminal on
+ * "Repo <owner>-main is not provisioned".
+ *
+ * The check is the MCP's credential-free resource-registry read — the SAME read
+ * `tenant_checkout` gates on — reached the SAME way the app-binding writer +
+ * cli-signin-code seam reach the MCP:
+ *   GET {origin(MCP_APP_BINDING_URL)}/internal/preview-status?tenant=<appDomain>&app=storefront&tag=main
+ *     header  x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>
+ *     → 200 { owner, app, repo, provisioned, previewReleased } | 400 | 502
+ * Contract source of truth: tot-mcp src/server/preview-status-routes.ts. We gate on
+ * `provisioned` — the exact precondition `tenant_checkout` needs. We do NOT gate on
+ * `previewReleased`: it is (provisioned && preview-approved), which is FALSE for every
+ * store that hasn't shipped a preview yet — gating on it would block invites for
+ * provisioned-but-unreleased stores whose checkout would actually succeed.
+ *
+ * FAIL-OPEN: we BLOCK only on a DEFINITIVE not-ready answer (a clean 200 with
+ * previewReleased:false). An unconfigured seam (no URL/secret), a non-200, a
+ * transport/parse fault, or a timeout is INCONCLUSIVE → allow (log a warning),
+ * mirroring recordDeveloperAppBinding's "skipped when not-configured" stance — we
+ * never break invites just because the MCP is briefly unreachable.
+ */
+import { readEnv } from "@/lib/env";
+
+/** How long we'll wait on the preview-status read before failing open. */
+const PREFLIGHT_TIMEOUT_MS = 4000;
+
+/** GET transport seam (injectable for tests) — mirrors HttpTransport but read-only. */
+export interface PreflightTransport {
+  get(
+    url: string,
+    headers: Record<string, string>,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+/** The real transport: a timeout-bounded GET. */
+export class FetchPreflightTransport implements PreflightTransport {
+  async get(url: string, headers: Record<string, string>) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), PREFLIGHT_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: ctrl.signal });
+      return { status: res.status, json: () => res.json() };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** BLOCK carries the inviter-facing message; ALLOW carries a reason (for logging). */
+export type PreflightDecision =
+  | { block: true; reason: "not-provisioned"; message: string }
+  | { block: false; reason: string };
+
+/** The inviter-facing block message, naming the store. */
+function blockMessage(tenant: string): string {
+  return (
+    `${tenant} isn't set up on this environment yet — its store repo isn't ` +
+    `provisioned. Finish provisioning that store before inviting a developer to it.`
+  );
+}
+
+/**
+ * Preflight `tenant` (the target appDomain). Returns a BLOCK only on a definitive
+ * not-provisioned answer; every inconclusive condition allows (fail-open). Never
+ * throws.
+ */
+export async function checkStorePreviewReady(
+  tenant: string,
+  deps: { transport?: PreflightTransport } = {},
+): Promise<PreflightDecision> {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!bindingUrl || !secret) {
+    // Seam not configured (the MCP route isn't even mounted without the secret) —
+    // inconclusive, so allow rather than break every invite.
+    return { block: false, reason: "not-configured" };
+  }
+
+  let endpoint: string;
+  try {
+    const origin = new URL(bindingUrl).origin;
+    const q = new URLSearchParams({ tenant: tenant.toLowerCase(), app: "storefront", tag: "main" });
+    // Canonical, namespace-neutral path (the read is generic, not dev-role-scoped).
+    endpoint = `${origin}/internal/preview-status?${q.toString()}`;
+  } catch {
+    return { block: false, reason: "bad-mcp-url" };
+  }
+
+  const transport = deps.transport ?? new FetchPreflightTransport();
+  let res: { status: number; json(): Promise<unknown> };
+  try {
+    res = await transport.get(endpoint, { "x-mcp-service-secret": secret });
+  } catch (cause) {
+    return {
+      block: false,
+      reason: "preflight request failed: " + (cause instanceof Error ? cause.message : String(cause)),
+    };
+  }
+
+  // Only a clean 200 is a conclusive answer; anything else is inconclusive → allow.
+  if (res.status < 200 || res.status >= 300) {
+    return { block: false, reason: `preflight returned status ${res.status}` };
+  }
+  let payload: { provisioned?: unknown; previewReleased?: unknown };
+  try {
+    payload = (await res.json()) as typeof payload;
+  } catch {
+    return { block: false, reason: "unparseable preflight response" };
+  }
+  // Gate on `provisioned` — the ONE precondition the invitee's first `tot start`
+  // checkout needs (a missing repo is the austin→sample-store failure). Treat only
+  // an explicit `false` as a definitive block; a missing/non-boolean field is
+  // inconclusive → allow. NOT `previewReleased` (see the file header): that now means
+  // provisioned && preview-approved, which is false for every not-yet-shipped store and
+  // would block invites whose checkout actually succeeds.
+  if (payload.provisioned === false) {
+    return { block: true, reason: "not-provisioned", message: blockMessage(tenant) };
+  }
+  return { block: false, reason: "provisioned" };
+}

package/apps/storefront/src/lib/webhooks/deliveryEngine.ts

@@ -24,8 +24,6 @@
  */
 import { WebhookDeliveryStore, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
 import type { AppInstall } from "../apps/registryService.js";
-import { loadWebhookSigningConfig, type WebhookSigningConfig } from "./webhookSigningKey.js";
-import { signWebhookRequest, type SignWebhookRequestResult } from "./signing.js";
 import { buildCloudEventEnvelope } from "./events.js";
 import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
 import { validateWebhookEndpoint } from "./endpointGuard.js";
@@ -33,6 +31,28 @@ import { validateWebhookEndpoint } from "./endpointGuard.js";
 /** Bounded per-attempt timeout — a hung receiver must not hold a dispatcher slot open indefinitely. */
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+// Both signing.js and webhookSigningKey.js ultimately re-export from
+// @tokenoftrust/private-apps-devkit, a workspace-only package never vendored
+// into the public storefront-runner — a static import of either (type-only
+// included: `tsc` resolves a module for `import type` too) would be a
+// dangling import in that build. The VALUES are loaded via dynamic import at
+// their call sites below (see attemptDelivery/deliverSigned); these two
+// shapes are duplicated here, type-only, so this module's own types don't
+// need those files to exist in the runner. Keep in sync with
+// webhookSigningKey.ts's WebhookSigningConfig and
+// private-apps-devkit/src/signing.ts's SignWebhookRequestResult.
+interface WebhookSigningConfig {
+  key: CryptoKey;
+  kid: string;
+}
+interface SignWebhookRequestResult {
+  headers: {
+    "content-digest": string;
+    "signature-input": string;
+    signature: string;
+  };
+}
+
 /** The minimal registry seam the engine needs: resolving the target install by id. Satisfied by `AppRegistryService`. */
 export interface InstallResolver {
   get(installId: string): Promise<AppInstall | null>;
@@ -83,7 +103,17 @@ export async function attemptDelivery(deliveryId: string, deps: AttemptDeliveryD
   const now = deps.now ?? (() => new Date());
   const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const fetchImpl = deps.fetchImpl ?? fetch;
-  const loadSigningConfig = deps.loadSigningConfig ?? loadWebhookSigningConfig;
+  const loadSigningConfig =
+    deps.loadSigningConfig ??
+    (async () => {
+      // Absent from the public storefront-runner (dropped; see WebhookSigningConfig above).
+      // ts-ignore, not ts-expect-error: this module DOES exist in the full repo's own
+      // typecheck (only missing from the runner-extracted tree), so there's no error to
+      // "expect" here in that context — ts-expect-error would itself error as unused.
+      // @ts-ignore
+      const mod = await import("./webhookSigningKey.js");
+      return mod.loadWebhookSigningConfig() as Promise<WebhookSigningConfig>;
+    });
 
   const delivery = await store.getDelivery(deliveryId);
   if (!delivery) {
@@ -172,7 +202,11 @@ async function deliverSigned(
     now: ctx.now,
   });
   const body = JSON.stringify(envelope);
-  const { headers } = await signWebhookRequest({
+  // Absent from the public storefront-runner (dropped; see SignWebhookRequestResult above);
+  // ts-ignore not ts-expect-error, same reasoning as loadSigningConfig above.
+  // @ts-ignore
+  const { signWebhookRequest } = await import("./signing.js");
+  const { headers }: SignWebhookRequestResult = await signWebhookRequest({
     method: "POST",
     url: install.webhookEndpoint!,
     body,

package/apps/storefront/src/lib/webhooks/emit.ts

@@ -48,7 +48,7 @@
 import { WebhookDeliveryStore, type WebhookTopic } from "./deliveryStore.js";
 import { TOPIC_REQUIRED_SCOPE } from "./events.js";
 import { getDispatcher } from "./getDispatcher.js";
-import { getRegistryService } from "../apps/adminService.js";
+import { getRegistryService } from "../apps/registryAccess.js";
 import type { AppInstall } from "../apps/registryService.js";
 import { fromD1 } from "../d1/catalog.js";
 import { readD1 } from "../env.js";

package/apps/storefront/src/lib/webhooks/getDispatcher.ts

@@ -21,7 +21,7 @@ import { CloudflareQueueDispatcher, type CloudflareQueueSender } from "./cloudfl
 import { AppRegistryService } from "../apps/registryService.js";
 import { D1CredentialStore } from "../apps/credentials.js";
 import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "../apps/gatewayKeys.js";
-import { json } from "../apps/adminService.js";
+import { json } from "../apps/registryAccess.js";
 import { fromD1 } from "../d1/catalog.js";
 import { readD1, readEnv, readQueue } from "../env.js";
 

package/apps/storefront/src/pages/api/auth/magic-exchange.ts

@@ -25,7 +25,7 @@ import {
 } from "@/lib/auth/identityToken";
 import { createSession, DEFAULT_SESSION_TTL_SECONDS } from "@/lib/auth/session";
 import { normalizeEmailHint } from "@/lib/privacy/emailHint";
-import { acceptDeveloperInvite } from "@/lib/grants/developerInvites";
+import { acceptDeveloperInvite } from "@/lib/shared/developerInvites";
 
 export const prerender = false;
 

package/apps/storefront/src/pages/index.astro

@@ -17,7 +17,7 @@ import TierCards from "@/components/membership/TierCards.astro";
 import { withBase } from "@/lib/basePath";
 import { rawHtmlPolicy, rawHtmlResponse } from "@/lib/rawMarketingHtml";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
-import { getRegistryService } from "@/lib/apps/adminService.js";
+import { getRegistryService } from "@/lib/apps/registryAccess.js";
 import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 import type { CatalogCollection, CatalogProduct } from "@tot/public-runtime";
 import {

package/apps/storefront/src/pages/products/[handle].astro

@@ -42,7 +42,7 @@ import { productLd, breadcrumbLd, reviewLd } from "@/lib/jsonld";
 import { isUsableImageUrl } from "@/lib/placeholder";
 import { withBase } from "@/lib/basePath";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
-import { getRegistryService } from "@/lib/apps/adminService.js";
+import { getRegistryService } from "@/lib/apps/registryAccess.js";
 import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 
 const { handle } = Astro.params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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/public-runtime/node_modules/.bin/tsc

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../typescript/bin/tsc" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi
+# cmd-shim-target=/home/runner/work/storefront/storefront/storefront-runner-dist/packages/public-runtime/node_modules/typescript/bin/tsc

package/packages/public-runtime/node_modules/.bin/tsserver

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../typescript/bin/tsserver" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi
+# cmd-shim-target=/home/runner/work/storefront/storefront/storefront-runner-dist/packages/public-runtime/node_modules/typescript/bin/tsserver

package/packages/public-runtime/node_modules/.bin/vitest

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../vitest/vitest.mjs" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi
+# cmd-shim-target=/home/runner/work/storefront/storefront/storefront-runner-dist/packages/public-runtime/node_modules/vitest/vitest.mjs

package/pnpm-workspace.yaml

@@ -1,6 +1,9 @@
 packages:
   - "apps/*"
   - "packages/*"
+allowBuilds:
+  esbuild: set this to true or false
+  workerd: set this to true or false
 linkWorkspacePackages: true
 onlyBuiltDependencies:
   - esbuild

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();