@tokenoftrust/storefront-runner 2.0.16 → 2.0.18

package/apps/storefront/src/middleware/renderChain.ts

@@ -0,0 +1,685 @@
+/**
+ * The render chain both serving branches share: static-bundle serving, the
+ * integration plane, the edge page cache, theme/content/capability resolution,
+ * the render itself, and the response headers stamped over it.
+ *
+ * Everything that needs D1 arrives as an already-resolved INPUT. That is what
+ * keeps the public branch free of a request-time D1 read: `publicRender` passes
+ * the empty/absent forms, `controlPlane` passes what it read. This module
+ * imports no D1 reader of its own.
+ */
+import type { APIContext, MiddlewareNext } from "astro";
+import { referenceTheme } from "@/themes/reference";
+import { mergeTheme, themeToCssVars } from "@/themes/schema";
+import { createToTClient } from "@/lib/tot/ToTClient";
+import { readEnv } from "@/lib/runtimeEnv";
+import { tryServeStaticBundle } from "./staticBundle.js";
+import { resolveCandidateContentPin } from "./candidatePin.js";
+import { createContentProvider, DevDraftContentProvider } from "@/lib/storyblok/provider";
+import { DEV_DRAFT_COOKIE, devDraftKey, verifyDevDraftToken } from "@/lib/dev/devDraft";
+import {
+  isCacheablePath,
+  pageCacheKey,
+  readCacheVersion,
+  getCachedPage,
+  putCachedPage,
+} from "@/lib/edgeCache";
+import { STATIC_SCRIPT_HASHES, STATIC_STYLE_HASHES } from "@/lib/cspStaticHashes";
+import { applySecurityHeaders } from "@/lib/securityHeaders";
+import { maybeInjectPreviewReload } from "@/lib/previewReload";
+import {
+  resolveCustomizationEnv,
+  buildCsp,
+  STOREFRONT_CSP_ALLOWLIST,
+  checkoutCspAdditions,
+  appWidgetCspAdditions,
+  embedCspAdditions,
+  foldIntegrationCsp,
+  embedsArtifactPath,
+  resolveEffectiveEmbeds,
+  CSP_REPORT_GROUP,
+  CSP_REPORT_PATH,
+  readPublishedArtifact,
+  themeArtifactPath,
+  resolveTenantFeatures,
+  resolveCapabilities,
+  capabilitiesArtifactPath,
+  resolveServableChannelVersion,
+  channelFromEnv,
+  resolveEnvironmentOnlyPlan,
+  resolveInterimBridgePlan,
+  compileIntegrationCspFromPlan,
+  collectDeclaredCspProfiles,
+  INTEGRATION_NONCE_PLACEHOLDER,
+  defaultConsentSnapshot,
+  parseConsentSnapshot,
+  CONSENT_SNAPSHOT_INPUT_HEADER,
+  CONSENT_SNAPSHOT_SIG_HEADER,
+  CONSENT_SNAPSHOT_HMAC_SECRET_BINDING,
+  MATERIALIZE_MODE_BINDING,
+  verifyConsentSnapshotSig,
+} from "@tot/public-runtime";
+import type {
+  CapabilityConfig,
+  ConsentSnapshot,
+  DeepPartial,
+  IntegrationDeclarationInput,
+  TenantConfig,
+  ThemeTokens,
+  BrowserEnvironment,
+} from "@tot/public-runtime";
+import {
+  formatHtmlCacheControl,
+  HTML_CACHE_POLICY_CAPTURE_HEADER,
+  HTML_CACHE_POLICY_CAPTURE_PROBE,
+} from "@tot/public-runtime";
+import { loadTenantIntegrationDeclarations } from "@/lib/integration/tenantDeclarations";
+import { resolveTenantCommerce } from "@/lib/checkoutCommerce";
+import { requestBrowserEnvironment, deriveSiteSurface, cspHeaderName } from "@/lib/integration/browserEnvironment";
+import { freshNonce, stampResponseNonce } from "@/lib/integration/nonceStamp";
+import { recordActivity } from "@/lib/activity/recordActivity";
+
+export interface RenderChainInput {
+  context: APIContext;
+  next: MiddlewareNext;
+  host: string;
+  url: URL;
+  tenant: TenantConfig;
+  basePath: string;
+  /** Tenant-relative path (selection prefix stripped). */
+  renderPath: string;
+  /** Workers Cache API default cache; undefined under `astro dev`. */
+  cache: Cache | undefined;
+  kv: KVNamespace | undefined;
+  /**
+   * Managed-install declarations, read from D1 by the caller. Empty on the public
+   * branch: a managed install is admin-installed state, and ADR 0013 puts that
+   * behind a publish-time bake, never a per-request read on the public path.
+   */
+  managedIntegrationDeclarations: readonly IntegrationDeclarationInput[];
+  /**
+   * Reads the tenant's saved consent revision (D1). `null` on the public branch,
+   * which falls back to the fail-closed essential-only default — the posture the
+   * baked-snapshot path already documents for the public/materialize render.
+   */
+  readTenantConsentSnapshot: (() => Promise<ConsentSnapshot | null>) | null;
+  /**
+   * Resolves the D1 catalog read replica. `null` on the public branch. Called at
+   * the point the catalog is actually built — after the static bundle and the
+   * edge cache have each had their chance to answer — so a request served from R2
+   * or a warm cache entry costs no D1 read. Typed off `createToTClient`'s own
+   * parameter rather than the D1 module, so this file names no D1 type at all.
+   */
+  readCatalogD1: (() => Promise<Parameters<typeof createToTClient>[1]>) | null;
+}
+
+export async function runRenderChain(input: RenderChainInput): Promise<Response> {
+  const { context, next, host, url, tenant, basePath, renderPath, cache, kv } = input;
+  const { request, locals } = context;
+
+  // Preview/test detection (also reused for the customization env below). A
+  // production read is one with no preview host, query token, or preview cookie.
+  const isPreviewHost = host.toLowerCase().startsWith("preview.");
+  const queryToken = url.searchParams.get("__preview");
+  const cookieToken = context.cookies.get("tot_preview")?.value ?? null;
+
+  // Candidate-render CONTENT PIN (`__tot_candidate_pin`): a signed, tenant- and
+  // expiry-bound token minted ONLY by the control-plane candidate/revision
+  // renderers (`src/lib/preview/pinnedRouteRender.ts`, never client-forgeable)
+  // that pins THIS one render's content resolution to an exact immutable
+  // `versionId`, bypassing the shared `{live,test}` channel entirely. It rides
+  // an in-process `context.rewrite()` from those renderers so a real Astro
+  // route (blog, editorial pages, …) — not just the raw `home.html`/
+  // `pages-html/*` documents they serve directly — renders pinned to the
+  // candidate under review (fb-1788536381607). Verified against this tenant so a
+  // pin can only ever name its own version; a mismatched/expired/absent token
+  // falls through to the normal channel-resolved read below, same fail-closed
+  // posture as the `__preview` token.
+  const candidatePin = await resolveCandidateContentPin(url, tenant.tenant_id);
+  // Per-developer AI-edit draft: the signed
+  // tot_dev_draft cookie's mere PRESENCE opts the request out of the shared page
+  // cache below (a draft view must never be cached publicly); it's verified —
+  // signature, expiry, tenant binding — before the overlay is applied further down.
+  const draftCookie = context.cookies.get(DEV_DRAFT_COOKIE)?.value ?? null;
+
+  const managedIntegrationDeclarations = input.managedIntegrationDeclarations;
+
+  // Digest-addressed static-bundle serving. Deliberately BEFORE the edge page
+  // cache / catalog / theme / customization machinery below: none of that applies
+  // to bundle bytes served verbatim, and once eligible that path must fully own
+  // the response rather than degrade into the normal render.
+  const bundled = await tryServeStaticBundle({
+    request,
+    url,
+    tenant,
+    basePath,
+    cache,
+    kv,
+    isPreviewHost,
+    hasPreviewToken: !!queryToken || !!cookieToken,
+    hasCandidatePin: !!candidatePin,
+    hasDraftCookie: !!draftCookie,
+    hasManagedInstalls: managedIntegrationDeclarations.length > 0,
+  });
+  if (bundled) return bundled;
+
+  // ---- Tenant-local integration materialization (ext-kernel-09) --------------
+  // Resolve a tenant's OWN declared, exact-version integrations into the effective
+  // plan the render engine serves, THROUGH the interim marketing bridge (which
+  // refuses a regulated tenant and fail-closes an invalid declaration set). Done
+  // HERE, before the edge-cache read, so a declared tenant's `planRevision` folds
+  // into the page-cache key below (a rollback/uninstall resolves a new revision →
+  // the old warm entry is unreachable → a clean re-render without the removed
+  // origins, never a TTL wait) AND its reviewed CSP origins reach the strict header.
+  //
+  // An UNDECLARED tenant does NONE of this: `loadTenantIntegrationDeclarations`
+  // returns the empty set, so `integrationCsp` stays undefined (the page-cache key
+  // is byte-identical to the non-integration form) and the environment-only plan is
+  // resolved below exactly as before — zero cost.
+  let resolvedBrowserEnvironment: BrowserEnvironment | null = null;
+  const integrationDeclarations = [
+    ...loadTenantIntegrationDeclarations(tenant),
+    ...managedIntegrationDeclarations,
+  ];
+  if (integrationDeclarations.length > 0) {
+    const declPreviewSecret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+    const declEnv = await resolveCustomizationEnv({
+      isPreviewHost,
+      tenantId: tenant.tenant_id,
+      token: queryToken ?? cookieToken,
+      secret: declPreviewSecret,
+      nowSeconds: Math.floor(Date.now() / 1000),
+      pathname: url.pathname,
+    });
+    const declFeatures = resolveTenantFeatures(tenant);
+    resolvedBrowserEnvironment = requestBrowserEnvironment({
+      host,
+      isPreviewHost,
+      customizationEnv: declEnv.env,
+      canonicalHost: tenant.canonicalDomain || host,
+      siteSurface: deriveSiteSurface({ catalog: declFeatures.catalog, pathname: renderPath }),
+    });
+    const bridge = resolveInterimBridgePlan({
+      tenantPublicId: tenant.tenant_id,
+      tenant,
+      environment: resolvedBrowserEnvironment,
+      declarations: integrationDeclarations,
+    });
+    if (bridge.ok) {
+      // A resolved plan serves; its compiled CSP additions + `planRevision` reach the
+      // cache key and the header. A refusal (regulated) or an invalid set leaves the
+      // plan unset here → the environment-only fallback below fills it (nothing loads).
+      locals.integrationPlan = bridge.plan;
+      const compiled = compileIntegrationCspFromPlan(
+        bridge.plan,
+        collectDeclaredCspProfiles(integrationDeclarations),
+      );
+      if (compiled.ok) locals.integrationCsp = compiled.value;
+    }
+  }
+
+  // ---- Consent snapshot: the tenant's ACTUAL initial consent state, not a
+  // hardcoded default. Both document mounts (Layout.astro, rawHtmlResponse) inline
+  // THIS value; an unresolved tenant stays on the fail-closed essential-only default.
+  locals.consentSnapshot = defaultConsentSnapshot();
+  // BAKED-SNAPSHOT INPUT (ADR 0013), honored ONLY on the materialize render, ONLY
+  // under a valid tenant-bound signature. The go-live bake pipeline resolves the
+  // tenant's REAL snapshot from D1 ONCE on the Worker, signs it, and provides
+  // {snapshot, sig} to the materialize render via these materialize-only request
+  // headers — so the static bundle inlines the real snapshot with NO consent D1
+  // read on the public/materialize path. TWO gates make the header un-forgeable:
+  //   1. MATERIALIZE-MODE binding: honored only when `TOT_MATERIALIZE_MODE` is set — a
+  //      binding the materializer's wrangler dev injects and the DEPLOYED Worker never
+  //      has. So a client cannot forge consent on the live Worker (which serves
+  //      preview/admin/gated + the public static bundle), and no cacheable response ever
+  //      varies on the header (it is never read there, so it cannot enter a cache key).
+  //   2. HMAC signature over a length-prefixed framing of (tenant_id, snapshot),
+  //      verified constant-time against the go-live secret and THIS tenant's id — so a
+  //      caller who forges the dispatch payload (no secret) or replays another tenant's
+  //      signed snapshot is rejected.
+  // Either gate failing ⇒ fall through to the caller-supplied reader (control plane
+  // only), never a caller-supplied snapshot.
+  let bakedConsent: ReturnType<typeof parseConsentSnapshot> = null;
+  if ((await readEnv(MATERIALIZE_MODE_BINDING)) === "1") {
+    const consentInputHeader = request.headers.get(CONSENT_SNAPSHOT_INPUT_HEADER);
+    const consentSig = request.headers.get(CONSENT_SNAPSHOT_SIG_HEADER);
+    const hmacSecret = await readEnv(CONSENT_SNAPSHOT_HMAC_SECRET_BINDING);
+    if (
+      consentInputHeader &&
+      hmacSecret &&
+      (await verifyConsentSnapshotSig(hmacSecret, tenant.tenant_id, consentInputHeader, consentSig))
+    ) {
+      bakedConsent = parseConsentSnapshot(consentInputHeader);
+    }
+  }
+  if (bakedConsent) {
+    locals.consentSnapshot = bakedConsent;
+  } else if (input.readTenantConsentSnapshot) {
+    const saved = await input.readTenantConsentSnapshot();
+    if (saved) locals.consentSnapshot = saved;
+  }
+
+  // ---- Edge page cache: short-circuit production browse reads on a hit,
+  // BEFORE building the client / theme / rendering. Misses store the final
+  // response at the end of this middleware.
+  //
+  // NEVER in dev (`astro dev`): the workerd dev runtime persists the Workers Cache
+  // API in .wrangler/state, so a cached page would be served stale across edits AND
+  // restarts — silently defeating hot-reload (edits look "lost"). Dev must always
+  // re-render. import.meta.env.DEV statically drops this guard from the prod build.
+  const pageCacheEligible =
+    !import.meta.env.DEV &&
+    request.method.toUpperCase() === "GET" &&
+    !isPreviewHost &&
+    !queryToken &&
+    !cookieToken &&
+    !candidatePin &&
+    !draftCookie &&
+    isCacheablePath(url.pathname, url.searchParams);
+  let pageKey: Request | null = null;
+  if (pageCacheEligible && cache && kv) {
+    const version = await readCacheVersion(kv, tenant.tenant_id);
+    // Fold the resolved integration plan revision into the key so a warm entry is
+    // version-scoped: a rollback/uninstall resolves a new revision → old entry
+    // unreachable → clean re-render without the removed origins (never a TTL wait).
+    // Undefined until the integration plane is resolved for this tenant — the key
+    // is then byte-identical to the non-integration form. The store below reuses
+    // this same `pageKey`, so read and write stay consistent.
+    pageKey = pageCacheKey(
+      tenant.tenant_id,
+      url.pathname,
+      url.search,
+      version,
+      locals.integrationCsp?.planRevision,
+    );
+    const hit = await getCachedPage(cache, pageKey);
+    // The cached artifact is nonce-free (carries the placeholder). Stamp a fresh
+    // per-response nonce into its body + CSP header so a warm hit is served with a
+    // brand-new nonce, never the one an earlier response rendered with.
+    if (hit) return await stampResponseNonce(hit, freshNonce());
+  }
+
+  // Catalog source selection (docs/architecture/product-catalog.md).
+  // A store's product source graduates over its life: JSON fixtures (dev default) ->
+  // D1 edge replica (staging) -> hosted ToT catalog (go-live). The read backend is
+  // chosen by the CALLER: the control plane resolves the D1 edge replica when
+  // USE_D1_CATALOG=1; the public branch never does, so `createToTClient` falls back
+  // to the bundled JSON fixture snapshot. The hosted catalog graduates the SAME
+  // canonical records into the D1 read model (emitCatalogSql), so JSON/D1/hosted
+  // render identically — pinned by lib/tot/sourceSelection.test.ts.
+  const tot = await createToTClient(tenant, await input.readCatalogD1?.());
+
+  const proto = url.protocol === "http:" ? "http" : "https";
+  // Canonical base uses the tenant's canonical domain in prod; for local dev we
+  // keep the actual host (plus any /<domain> base path) so links resolve.
+  const isLocal = host.startsWith("localhost") || host.startsWith("127.0.0.1");
+  const canonicalBase = isLocal
+    ? `${proto}://${host}${basePath}`
+    : `https://${tenant.canonicalDomain}`;
+
+  // Live vs test customization. Production hosts always serve "live" and
+  // ignore any token; a "preview." host is auth-gated by a signed, tenant-bound,
+  // short-TTL preview token (?__preview= on first hit, then the tot_preview
+  // cookie). Test is never indexable (X-Robots-Tag below).
+  const previewToken = queryToken ?? cookieToken;
+  const previewSecret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const customization = await resolveCustomizationEnv({
+    isPreviewHost,
+    tenantId: tenant.tenant_id,
+    token: previewToken,
+    secret: previewSecret,
+    nowSeconds,
+    pathname: url.pathname,
+  });
+  if (customization.reject) {
+    return new Response(customization.reject.message, {
+      status: customization.reject.status,
+    });
+  }
+  // Persist a query-supplied token as a cookie so later navigations stay in test.
+  if (customization.env === "test" && queryToken) {
+    context.cookies.set("tot_preview", queryToken, {
+      httpOnly: true,
+      secure: true,
+      sameSite: "lax",
+      path: "/",
+      maxAge: 3600,
+    });
+  }
+
+  // Apply a published theme override for the resolved environment (store->app).
+  // The live domain serves `live`; a gated preview serves `test`. When nothing
+  // is published the build-time tenant theme is used unchanged.
+  //
+  // Resolution is versioned-aware inside readPublishedArtifact: env maps to a
+  // publish channel (live->live, test->preview); if the tenant has a channel
+  // pointer, the artifact is resolved through the immutable site version
+  // (channel -> versionId -> manifest -> content). Tenants with no channel
+  // pointer fall back to the legacy per-path selection — no behavior change.
+  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+
+  // Self-heal a DANGLING channel pointer: the pointer for this env's channel may
+  // name a version that was never built (or whose manifest was evicted).
+  // `readVersionedArtifact` already serves last-built content instead of emptying
+  // the surface; here we do the once-per-request detection to ENQUEUE a rebuild of
+  // the dangling version. Fail-open: a KV hiccup never blocks the render (the reads
+  // below still run).
+  if (kv) {
+    const channel = channelFromEnv(customization.env);
+    await resolveServableChannelVersion(kvGet, tenant.tenant_id, channel, ({ versionId }) => {
+      recordActivity({
+        action: "preview.build.requested",
+        actor: { kind: "system", id: "storefront" },
+        source: "server",
+        outcome: { status: "succeeded" },
+        scope: { tenantId: tenant.tenant_id },
+        payload: { args: { changeId: versionId } },
+      });
+    }).catch(() => {
+      /* fail-open: self-heal detection never breaks the request */
+    });
+  }
+
+  // Verify the developer-draft cookie (signature + expiry + tenant binding) — the
+  // overlay below only engages for the developer who minted the draft, on THIS
+  // tenant. Same secret + trust model as the preview token; invalid/expired/foreign
+  // tokens degrade silently to the base chain (never an error page).
+  const draftClaims =
+    draftCookie && previewSecret && kv
+      ? await verifyDevDraftToken(previewSecret, draftCookie, nowSeconds)
+      : null;
+  const draft =
+    draftClaims && draftClaims.tenantId === tenant.tenant_id ? draftClaims : null;
+
+  let theme = mergeTheme(referenceTheme, tenant.theme_tokens);
+  const publishedTheme = await readPublishedArtifact(
+    kvGet,
+    tenant.tenant_id,
+    customization.env,
+    themeArtifactPath(tenant.tenant_id),
+  );
+  if (publishedTheme) {
+    try {
+      theme = mergeTheme(theme, JSON.parse(publishedTheme) as DeepPartial<ThemeTokens>);
+    } catch {
+      /* malformed published artifact — keep the build-time theme */
+    }
+  }
+  // Developer-draft theme overlay (on top of published) — only for the draft owner.
+  if (draft) {
+    const draftTheme = await kvGet(devDraftKey(tenant.tenant_id, draft.draftId, "theme.json"));
+    if (draftTheme) {
+      try {
+        theme = mergeTheme(theme, JSON.parse(draftTheme) as DeepPartial<ThemeTokens>);
+      } catch {
+        /* malformed draft artifact — keep the resolved theme */
+      }
+    }
+  }
+
+  // Per-environment capabilities (Track A/B). Config-as-code: the build-time
+  // TenantConfig default is overridden by the published capabilities artifact for
+  // THIS environment — materialized from the tenant repo's .tot/config.json per
+  // commit (localhost=working tree, preview=PR head, live=promoted). So a
+  // capability change is PR-gated and separable per environment.
+  let publishedCaps: Partial<CapabilityConfig> | null = null;
+  const publishedCapsRaw = await readPublishedArtifact(
+    kvGet,
+    tenant.tenant_id,
+    customization.env,
+    capabilitiesArtifactPath(tenant.tenant_id),
+  );
+  if (publishedCapsRaw) {
+    try {
+      publishedCaps = JSON.parse(publishedCapsRaw) as Partial<CapabilityConfig>;
+    } catch {
+      /* malformed published artifact — keep the build-time default */
+    }
+  }
+  const capabilities = resolveCapabilities(tenant, publishedCaps);
+
+  // Embed opt-in (self-serve, config-as-code on the same spine as capabilities):
+  // the build-time TenantConfig.embeds default is overlaid with the tenant's
+  // published embeds.json for THIS env, then filtered to the vetted catalog. A
+  // tenant enables a catalogued embed by committing embeds.json — no platform
+  // change — but can never introduce a non-catalog origin.
+  let publishedEmbeds: string[] | null = null;
+  const publishedEmbedsRaw = await readPublishedArtifact(
+    kvGet,
+    tenant.tenant_id,
+    customization.env,
+    embedsArtifactPath(tenant.tenant_id),
+  );
+  if (publishedEmbedsRaw) {
+    try {
+      const parsed = JSON.parse(publishedEmbedsRaw);
+      if (Array.isArray(parsed)) publishedEmbeds = parsed.filter((s) => typeof s === "string");
+    } catch {
+      /* malformed published artifact — keep the build-time default */
+    }
+  }
+  const effectiveEmbeds = resolveEffectiveEmbeds(tenant.embeds, publishedEmbeds);
+
+  // Nonce placeholder: the platform's inline tags AND the CSP header are rendered
+  // with this sentinel, never a live nonce (ADR 0018). A fresh per-response nonce
+  // is stamped in at serve time (stampResponseNonce below), so the cached artifact
+  // is nonce-free and every response — cold render or warm cache hit — gets a fresh
+  // matching nonce/CSP pair.
+  const cspNonce = INTEGRATION_NONCE_PLACEHOLDER;
+
+  locals.tenant = tenant;
+  // Effective capability flags for this tenant (commerce defaults unless the
+  // tenant declares siteType:"marketing" / explicit features). Pages and chrome
+  // read these instead of hard-coding tenant identity checks.
+  locals.features = resolveTenantFeatures(tenant);
+  locals.capabilities = capabilities;
+  // Cart/checkout facts (Track A) — only when the tenant has a catalog
+  // AND the cartCheckout capability is enabled for THIS environment. Drives the
+  // loader + signed add-to-cart, and the CSP additions below.
+  const commerce =
+    locals.features.catalog && capabilities.cartCheckout.enabled
+      ? await resolveTenantCommerce(tenant)
+      : null;
+  locals.commerce = commerce ?? undefined;
+  locals.tot = tot;
+  // A verified candidate content pin takes priority over the channel-resolved
+  // read — a pinned candidate/revision render must never fall through to the
+  // shared `{live,test}` content (see `pinnedRouteRender.ts`).
+  locals.content = candidatePin
+    ? createContentProvider(tenant, undefined, { get: kvGet, versionId: candidatePin.versionId })
+    : createContentProvider(tenant, {
+        get: kvGet,
+        env: customization.env,
+      });
+  // Developer-draft content overlay — serves the AI-edited artifacts to the draft
+  // owner only; every other viewer keeps the published/base chain above.
+  if (draft) {
+    locals.content = new DevDraftContentProvider(
+      locals.content,
+      tenant.tenant_id,
+      draft.draftId,
+      kvGet,
+    );
+  }
+  locals.themeStyle = themeToCssVars(theme);
+  locals.canonicalBase = canonicalBase;
+  locals.customizationEnv = customization.env;
+  locals.cspNonce = cspNonce;
+  // Seeded here, filled in by whichever page/layout renders a widget slot
+  // (renderSlot.ts) as the page renders inside next() below — read back out
+  // after next() resolves so the CSP frame-src reflects exactly what rendered.
+  locals.activeWidgetPlacements = [];
+  // Prefix that path-routed pages live under ("" for host-routed). Pages stay
+  // tenant-agnostic; the Layout uses this to keep root-absolute links inside
+  // the tenant prefix on the client. A candidate content pin overrides this to
+  // the PINNING render's own prefix (`/preview/rev/<sha>` or
+  // `/preview/render/<tenant>/<changeId>`) so a pinned page's OWN generated
+  // links stay inside that candidate instead of escaping to the live host.
+  locals.basePath = candidatePin ? candidatePin.basePath : basePath;
+  // Renderer-owned four-stage browser environment (ADR 0014 E1 / 0017), computed
+  // ONCE here from authoritative request state and serialized before app code by
+  // both document mounts (Layout.astro + rawHtmlResponse). The candidate render
+  // paths build their own `candidate`-stage object instead of this one.
+  // Reuse the environment resolved for a declared tenant's integration plane above
+  // (identical inputs → identical object) so the plan's environment and this object
+  // never diverge; an undeclared tenant computes it here for the first time.
+  locals.browserEnvironment =
+    resolvedBrowserEnvironment ??
+    requestBrowserEnvironment({
+      host,
+      isPreviewHost,
+      customizationEnv: customization.env,
+      canonicalHost: tenant.canonicalDomain || host,
+      siteSurface: deriveSiteSurface({ catalog: locals.features.catalog, pathname: renderPath }),
+    });
+  // Resolved effective plan (ext-kernel-03) for this request — the fixed-phase
+  // render engine (ext-kernel-04) consumes it in BOTH document mounts (Layout.astro
+  // + rawHtmlResponse). A declared tenant's plan is already resolved above (through
+  // the interim bridge); an undeclared tenant — or one the bridge refused / failed
+  // closed — resolves the environment-only plan here, so a page with no serving
+  // integration emits no vendor runtime/markup.
+  locals.integrationPlan =
+    locals.integrationPlan ??
+    resolveEnvironmentOnlyPlan(locals.browserEnvironment, tenant.tenant_id);
+
+  // When a /<domain>/ prefix selected the tenant, rewrite to the stripped route
+  // so the existing file-based routes match. next(path) rewrites WITHOUT
+  // re-running middleware, so the locals set above are preserved.
+  let response = basePath
+    ? await next(`${renderPath}${url.search}`)
+    : await next();
+
+  // On-publish auto-refresh: inject the live-reload client into SHARED preview
+  // (`test`) HTML pages ONLY — never `live` (keeps live clean + edge-cacheable).
+  // It polls /__preview/version and reloads when this tenant's cache-version
+  // bumps on publish/reconcile. Injection happens before the CSP header is set so
+  // the script's per-request nonce (cspNonce) matches the enforced policy.
+  response = await maybeInjectPreviewReload(response, {
+    env: customization.env,
+    tenantId: tenant.tenant_id,
+    basePath,
+    nonce: cspNonce,
+  });
+
+  // Baseline security headers on every response — set before the page-cache
+  // store below so cached copies carry them too.
+  applySecurityHeaders(response.headers);
+
+  // Preview (test) output must never be indexed.
+  if (customization.noindex) {
+    response.headers.set("X-Robots-Tag", "noindex, nofollow");
+  }
+
+  // Strict CSP — now ENFORCED in every environment (Epic S2). The report-only
+  // rollout is complete: platform output is CSP-clean — inline styles are
+  // externalized (`inlineStylesheets: "never"`), Astro's static inline scripts +
+  // island style are hash-pinned (cspStaticHashes), our dynamic inline tags carry
+  // the per-request nonce, and the last inline event handler (SortSelect's
+  // `onchange`) is now a bundled 'self' script. Reporting endpoints stay attached
+  // (report-to/report-uri work in enforce mode), so we keep telemetry as tenant
+  // client JS arrives — those per-version tenant hashes extend `scriptSrc` per
+  // request (the mechanism below already supports it).
+  //
+  // DEV EXCEPTION: `astro dev` serves CSS/HMR as UN-nonced inline <style>/<script>
+  // (Vite injects them); the strict nonce policy blocks those, leaving the dev
+  // site unstyled. The BUILD is CSP-clean (styles are externalized via
+  // `inlineStylesheets:"never"`), so we enforce there and only REPORT in dev —
+  // violations are still surfaced, but styling/HMR work locally.
+  const cspHeader = cspHeaderName(import.meta.env.DEV);
+  response.headers.set(
+    "Reporting-Endpoints",
+    `${CSP_REPORT_GROUP}="${CSP_REPORT_PATH}"`,
+  );
+  // Checkout origins (loader CDN + the store's cart/checkout host) added to the
+  // strict policy only when this tenant has a store — so add-to-cart, the
+  // sidecart iframe/XHR, and the cross-origin form POST all pass.
+  const checkoutCsp = commerce ? checkoutCspAdditions(commerce.origin) : null;
+  // Private-app widget origins — read back AFTER next() so this reflects
+  // exactly the placements that rendered on THIS page, never a wildcard.
+  const widgetCsp = appWidgetCspAdditions(locals.activeWidgetPlacements ?? []);
+  // Third-party marketing embeds (e.g. a Pipedrive form) the tenant opted into
+  // via .tot/config.json `embeds:`. Only scan the HTML body when the tenant
+  // declared at least one embed — zero cost for everyone else — and add each
+  // provider's origins ONLY if its marker is actually on THIS page.
+  // Prefer an opt-in the render handler resolved for a tenant the URL router
+  // couldn't (the candidate renderer sets locals.embedOptIn — see candidateRender);
+  // otherwise use the router-resolved tenant's effective embeds.
+  const embedsForScan = locals.embedOptIn ?? effectiveEmbeds;
+  let embedCsp = { scriptSrc: [] as string[], connectSrc: [] as string[], frameSrc: [] as string[] };
+  if (
+    embedsForScan.length > 0 &&
+    (response.headers.get("content-type") ?? "").includes("text/html")
+  ) {
+    embedCsp = embedCspAdditions(embedsForScan, await response.clone().text());
+  }
+  const cspOptions = {
+    nonce: cspNonce,
+    ...STOREFRONT_CSP_ALLOWLIST,
+    // Pin Astro's static inline hydration scripts + island style by hash
+    // (they're identical every request); my dynamic inline tags use the nonce.
+    scriptSrc: [
+      ...STOREFRONT_CSP_ALLOWLIST.scriptSrc,
+      ...STATIC_SCRIPT_HASHES,
+      ...(checkoutCsp?.scriptSrc ?? []),
+      ...embedCsp.scriptSrc,
+    ],
+    styleSrc: [
+      ...STOREFRONT_CSP_ALLOWLIST.styleSrc,
+      ...STATIC_STYLE_HASHES,
+      ...(checkoutCsp?.styleSrc ?? []),
+    ],
+    fontSrc: [...STOREFRONT_CSP_ALLOWLIST.fontSrc, ...(checkoutCsp?.fontSrc ?? [])],
+    connectSrc: [
+      ...STOREFRONT_CSP_ALLOWLIST.connectSrc,
+      ...(checkoutCsp?.connectSrc ?? []),
+      ...embedCsp.connectSrc,
+    ],
+    imgSrc: [...STOREFRONT_CSP_ALLOWLIST.imgSrc, ...(checkoutCsp?.imgSrc ?? [])],
+    frameSrc: [
+      ...(checkoutCsp?.frameSrc ?? []),
+      ...widgetCsp.frameSrc,
+      ...embedCsp.frameSrc,
+    ],
+    formAction: checkoutCsp?.formAction ?? [],
+    reportGroup: CSP_REPORT_GROUP,
+    reportUri: CSP_REPORT_PATH,
+  };
+  // Version-scoped integration plane: APPEND the resolved plan's compiled origins
+  // (curated adapter profiles + advanced exact origins) to the six contributable
+  // directives only — never the base. Absent (no integration) this is a no-op, so
+  // the header is byte-identical to a non-integration tenant's.
+  response.headers.set(
+    cspHeader,
+    buildCsp(foldIntegrationCsp(cspOptions, locals.integrationCsp?.additions ?? {})),
+  );
+
+  // Store the fully-rendered, CSP-stamped response for the next reader. Only
+  // production (no preview token reached here) cacheable GETs have a pageKey;
+  // putCachedPage additionally skips non-200, non-HTML, and cookie-bearing
+  // responses. Also expose Cache-Control to any fronting CDN.
+  if (pageKey && cache && customization.env === "live") {
+    response.headers.set(
+      "Cache-Control",
+      "public, s-maxage=300, stale-while-revalidate=86400",
+    );
+    // Store the nonce-free artifact (the placeholder is still in the body + CSP
+    // header) BEFORE stamping — so the cache never holds a live/reusable nonce.
+    await putCachedPage(cache, pageKey, response);
+  }
+  // MATERIALIZE-ONLY capture (ADR 0013): expose the tenant's resolved route-document
+  // Cache-Control so the publish/materialize plane can bake it into the bundle
+  // manifest (the same capture pattern as CSP). Gated on the materialize probe
+  // request header, so it NEVER reaches a public client — the LIVE served header
+  // comes from the manifest via `static-bundle`, not from this signal.
+  if (request.headers.get(HTML_CACHE_POLICY_CAPTURE_PROBE)) {
+    response.headers.set(
+      HTML_CACHE_POLICY_CAPTURE_HEADER,
+      formatHtmlCacheControl(locals.tenant?.serving?.htmlCachePolicy),
+    );
+  }
+  // Stamp a fresh per-response nonce into this cold response's body + CSP header
+  // (the warm-hit path above stamps its own). Both paths therefore serve a fresh,
+  // matching nonce/CSP pair, and no nonce is reused across responses (ADR 0018).
+  return await stampResponseNonce(response, freshNonce());
+}