@tokenoftrust/storefront-runner 2.0.28 → 2.0.29

package/apps/storefront/env.d.ts

@@ -10,6 +10,7 @@ import type {
   BrowserEnvironment,
   CompiledIntegrationCsp,
   EffectivePlan,
+  IntegrationDeclarationInput,
   ConsentSnapshot,
   ResolvedRouteTierV1,
   PublicationRoutePlanV1,
@@ -170,6 +171,13 @@ declare global {
        * wired; carries no secret and no nonce.
        */
       integrationPlan: EffectivePlan;
+      /**
+       * The exact declaration set used to resolve this request's integration
+       * plan. Exact candidate/staged renderers reuse it with their server-owned
+       * stage and immutable revision; public browse requests never receive
+       * request-time managed declarations.
+       */
+      integrationDeclarations: readonly IntegrationDeclarationInput[];
       /**
        * The tenant's actual initial consent snapshot — computed once by the
        * middleware from its saved {@link TenantConsentConfig} (ext-admin-03) via

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -210,12 +210,14 @@ export function isStaticBundleUploadPath(pathname: string): boolean {
  *   /preview/change/<changeId>                the per-change review dashboard
  *   /<tenant>/preview/pr/<n>                  the friendly PR-number alias
  *   /<tenant>/preview/rev/<sha>/...           the immutable per-revision renderer
+ *   /<tenant>/preview/staged/<sha>/...        the immutable combined-release renderer
  */
 export function isCandidatePreviewPath(pathname: string): boolean {
   if (pathname.startsWith("/preview/render/")) return true;
   if (pathname === "/preview/change" || pathname.startsWith("/preview/change/")) return true;
   // /<tenant>/preview/pr and /<tenant>/preview/pr/<n> — the PR-number alias.
   if (/^\/[^/]+\/preview\/pr(?:\/|$)/.test(pathname)) return true;
+  if (/^\/[^/]+\/preview\/staged(?:\/|$)/.test(pathname)) return true;
   // /<tenant>/preview/rev/<sha> and /<tenant>/preview/rev/<sha>/<path...> — the
   // immutable per-revision alias.
   return /^\/[^/]+\/preview\/rev(?:\/|$)/.test(pathname);

package/apps/storefront/src/lib/integration/browserEnvironment.ts

@@ -12,12 +12,18 @@
  */
 import {
   resolveBrowserEnvironment,
-  resolveEnvironmentOnlyPlan,
   type BrowserEnvironment,
   type EffectivePlan,
+  type IntegrationDeclarationInput,
+  type IntegrationEnvironment,
   type IntegrationSiteSurface,
+  type ObligationTenant,
 } from "@tot/public-runtime";
 import { isAdminPath } from "@/lib/auth/loginGate";
+import {
+  resolveIntegrationRenderState,
+  type IntegrationRenderState,
+} from "@/lib/integration/renderIntegrationState";
 
 /**
  * The non-secret render revision: the commit SHA this build was cut from (baked at
@@ -109,11 +115,28 @@ export function candidateBrowserEnvironment(input: {
   canonicalHost: string;
   revision: string;
   siteSurface?: IntegrationSiteSurface;
+}): BrowserEnvironment {
+  return previewBrowserEnvironment({ ...input, stage: "candidate" });
+}
+
+/**
+ * The renderer-owned environment for an exact preview artifact. A per-change
+ * render is `candidate`; the combined release preview is `staged`. The stage is
+ * supplied only by the server-owned route that selected the artifact, never by
+ * query string or tenant content.
+ */
+export function previewBrowserEnvironment(input: {
+  canonicalHost: string;
+  revision: string;
+  stage: Extract<IntegrationEnvironment, "candidate" | "staged">;
+  siteSurface?: IntegrationSiteSurface;
 }): BrowserEnvironment {
   return resolveBrowserEnvironment({
-    dev: import.meta.env.DEV,
+    // This is an explicit server-owned preview route, even while exercised by
+    // Astro dev/Vitest. Do not let the process mode erase its signed stage.
+    dev: false,
     localHost: false,
-    candidate: true,
+    candidate: input.stage === "candidate",
     previewHost: true,
     customizationEnv: "test",
     siteSurface: input.siteSurface ?? "marketing",
@@ -123,15 +146,80 @@ export function candidateBrowserEnvironment(input: {
 }
 
 /**
- * The resolved effective plan for a candidate render — the `candidate`-stage
- * environment wrapped in an environment-only plan so `rawHtmlResponse` (the raw
- * mount of the fixed-phase engine) renders the same renderer-owned phases a live
- * page gets. No integration declarations are materialized on the candidate hot
- * path, so this is environment-only until that wiring lands.
+ * Resolve an exact preview artifact through the same declaration and regulated-
+ * tenant bridge as a normal page. Invalid declarations fail closed to an
+ * environment-only plan; a preview can never fall back to the live plan.
  */
+export function previewIntegrationPlan(
+  input: {
+    canonicalHost: string;
+    revision: string;
+    stage: Extract<IntegrationEnvironment, "candidate" | "staged">;
+    siteSurface?: IntegrationSiteSurface;
+  },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): EffectivePlan {
+  return previewIntegrationState(input, tenantPublicId, tenant, declarations).plan;
+}
+
+/** Resolve an exact preview plan and CSP atomically. */
+export function previewIntegrationState(
+  input: {
+    canonicalHost: string;
+    revision: string;
+    stage: Extract<IntegrationEnvironment, "candidate" | "staged">;
+    siteSurface?: IntegrationSiteSurface;
+  },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): IntegrationRenderState {
+  return resolveIntegrationRenderState({
+    tenantPublicId,
+    tenant,
+    environment: previewBrowserEnvironment(input),
+    declarations,
+  });
+}
+
+/** Resolve a per-change preview against the candidate destination set. */
 export function candidateIntegrationPlan(
   input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
   tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): EffectivePlan {
+  return previewIntegrationPlan({ ...input, stage: "candidate" }, tenantPublicId, tenant, declarations);
+}
+
+/** Resolve a combined-release preview against the staged destination set. */
+export function stagedIntegrationPlan(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
 ): EffectivePlan {
-  return resolveEnvironmentOnlyPlan(candidateBrowserEnvironment(input), tenantPublicId);
+  return previewIntegrationPlan({ ...input, stage: "staged" }, tenantPublicId, tenant, declarations);
+}
+
+/** Resolve a per-change preview plan and CSP atomically. */
+export function candidateIntegrationState(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): IntegrationRenderState {
+  return previewIntegrationState({ ...input, stage: "candidate" }, tenantPublicId, tenant, declarations);
+}
+
+/** Resolve a combined-release preview plan and CSP atomically. */
+export function stagedIntegrationState(
+  input: { canonicalHost: string; revision: string; siteSurface?: IntegrationSiteSurface },
+  tenantPublicId: string,
+  tenant: ObligationTenant,
+  declarations: readonly IntegrationDeclarationInput[],
+): IntegrationRenderState {
+  return previewIntegrationState({ ...input, stage: "staged" }, tenantPublicId, tenant, declarations);
 }

package/apps/storefront/src/lib/integration/renderIntegrationState.ts

@@ -0,0 +1,44 @@
+import {
+  collectDeclaredCspProfiles,
+  compileIntegrationCspFromPlan,
+  resolveEnvironmentOnlyPlan,
+  resolveInterimBridgePlan,
+  type BrowserEnvironment,
+  type CompiledIntegrationCsp,
+  type EffectivePlan,
+  type IntegrationDeclarationInput,
+  type ObligationTenant,
+} from "@tot/public-runtime";
+
+export interface IntegrationRenderState {
+  plan: EffectivePlan;
+  compiledCsp?: CompiledIntegrationCsp;
+}
+
+/**
+ * Resolve the plan and CSP as one fail-closed unit. A document either receives
+ * the reviewed plan with the CSP compiled from that exact plan, or an
+ * environment-only plan with no integration origins. Partial state never serves.
+ */
+export function resolveIntegrationRenderState(input: {
+  tenantPublicId: string;
+  tenant: ObligationTenant;
+  environment: BrowserEnvironment;
+  declarations: readonly IntegrationDeclarationInput[];
+}): IntegrationRenderState {
+  const fallback = (): IntegrationRenderState => ({
+    plan: resolveEnvironmentOnlyPlan(input.environment, input.tenantPublicId),
+  });
+  if (input.declarations.length === 0) return fallback();
+
+  const bridge = resolveInterimBridgePlan(input);
+  if (!bridge.ok) return fallback();
+
+  const compiled = compileIntegrationCspFromPlan(
+    bridge.plan,
+    collectDeclaredCspProfiles(input.declarations),
+  );
+  if (!compiled.ok) return fallback();
+
+  return { plan: bridge.plan, compiledCsp: compiled.value };
+}

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

@@ -14,6 +14,7 @@ import { CANDIDATE_CONTENT_PIN_PARAM, verifyContentPinToken } from "@tot/public-
 export interface CandidateContentPin {
   versionId: string;
   basePath: string;
+  integrationStage: "candidate" | "staged";
 }
 
 /**
@@ -31,5 +32,9 @@ export async function resolveCandidateContentPin(
   if (!secret) return null;
   const verified = await verifyContentPinToken(secret, param, Math.floor(Date.now() / 1000));
   if (!verified.ok || verified.claims.tenantId !== tenantId) return null;
-  return { versionId: verified.claims.versionId, basePath: verified.claims.basePath };
+  return {
+    versionId: verified.claims.versionId,
+    basePath: verified.claims.basePath,
+    integrationStage: verified.claims.integrationStage,
+  };
 }

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

@@ -49,9 +49,6 @@ import {
   resolveServableChannelVersion,
   channelFromEnv,
   resolveEnvironmentOnlyPlan,
-  resolveInterimBridgePlan,
-  compileIntegrationCspFromPlan,
-  collectDeclaredCspProfiles,
   INTEGRATION_NONCE_PLACEHOLDER,
   defaultConsentSnapshot,
   exactPublicationTimestamp,
@@ -82,8 +79,14 @@ import {
 } from "@tot/public-runtime";
 import { loadTenantIntegrationDeclarations } from "@/lib/integration/tenantDeclarations";
 import { resolveTenantCommerce } from "@/lib/checkoutCommerce";
-import { requestBrowserEnvironment, deriveSiteSurface, cspHeaderName } from "@/lib/integration/browserEnvironment";
+import {
+  requestBrowserEnvironment,
+  previewBrowserEnvironment,
+  deriveSiteSurface,
+  cspHeaderName,
+} from "@/lib/integration/browserEnvironment";
 import { freshNonce, stampResponseNonce } from "@/lib/integration/nonceStamp";
+import { resolveIntegrationRenderState } from "@/lib/integration/renderIntegrationState";
 import { recordActivity } from "@/lib/activity/recordActivity";
 import { middlewareRewriteTargetV1 } from "./routeBranch.js";
 import {
@@ -271,32 +274,32 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     ...loadTenantIntegrationDeclarations(tenant),
     ...managedIntegrationDeclarations,
   ];
+  locals.integrationDeclarations = integrationDeclarations;
   if (integrationDeclarations.length > 0) {
     const declFeatures = resolveTenantFeatures(tenant);
-    resolvedBrowserEnvironment = requestBrowserEnvironment({
-      host,
-      isPreviewHost,
-      customizationEnv: customization.env,
-      canonicalHost: tenant.canonicalDomain || host,
-      siteSurface: deriveSiteSurface({ catalog: declFeatures.catalog, pathname: renderPath }),
-    });
-    const bridge = resolveInterimBridgePlan({
+    const siteSurface = deriveSiteSurface({ catalog: declFeatures.catalog, pathname: renderPath });
+    resolvedBrowserEnvironment = candidatePin
+      ? previewBrowserEnvironment({
+          stage: candidatePin.integrationStage,
+          canonicalHost: tenant.canonicalDomain || host,
+          revision: candidatePin.versionId,
+          siteSurface,
+        })
+      : requestBrowserEnvironment({
+          host,
+          isPreviewHost,
+          customizationEnv: customization.env,
+          canonicalHost: tenant.canonicalDomain || host,
+          siteSurface,
+        });
+    const state = resolveIntegrationRenderState({
       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;
-    }
+    locals.integrationPlan = state.plan;
+    if (state.compiledCsp) locals.integrationCsp = state.compiledCsp;
   }
 
   // ---- Consent snapshot: the tenant's ACTUAL initial consent state, not a
@@ -586,13 +589,20 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // 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 }),
-    });
+    (candidatePin
+      ? previewBrowserEnvironment({
+          stage: candidatePin.integrationStage,
+          canonicalHost: tenant.canonicalDomain || host,
+          revision: candidatePin.versionId,
+          siteSurface: deriveSiteSurface({ catalog: locals.features.catalog, pathname: renderPath }),
+        })
+      : 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.28",
+  "version": "2.0.29",
   "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/src/customization-preview.ts

@@ -150,6 +150,8 @@ export const CANDIDATE_CONTENT_PIN_PARAM = "__tot_candidate_pin";
 export interface ContentPinClaims {
   tenantId: string;
   versionId: string;
+  /** Analytics stage selected by the server-owned preview route. */
+  integrationStage: "candidate" | "staged";
   /** basePath the pinned render's own generated links must stay under. */
   basePath: string;
   /** Expiry, epoch seconds. */
@@ -221,6 +223,7 @@ export async function verifyContentPinToken(
     !claims ||
     typeof claims.tenantId !== "string" ||
     typeof claims.versionId !== "string" ||
+    (claims.integrationStage !== "candidate" && claims.integrationStage !== "staged") ||
     typeof claims.basePath !== "string" ||
     typeof claims.exp !== "number"
   ) {