@tokenoftrust/storefront-runner 2.5.6 → 3.0.1

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

@@ -25,7 +25,7 @@ import { getTenantResolver } from "@/config/resolver";
 import { readEnv, readKv, readR2 } from "@/lib/publication/shared/runtimeEnv";
 import { resolveCdnForwardRouting, resolveTenantRouting } from "@/lib/access/shared/tenantRouting";
 import { crossSiteFormRefusal, verifyCdnForward } from "@/lib/publication/shared/cdnForward";
-import { compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
+import { SAMPLE_CART_HANDOFF_URL, compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
 import type { PublicationArtifactBucketV1, TenantConfig } from "@tot/public-runtime";
 import { DEV_DRAFT_COOKIE } from "@/lib/developer-experience/dev/devDraft";
 import { applySecurityHeaders } from "@/lib/access/shared/securityHeaders";
@@ -36,6 +36,7 @@ import { parseGateMode } from "@/lib/access/auth/loginGate";
 import { evaluateDemoGate, hostInGateList } from "@/lib/access/shared/demoGate";
 import { isMaintenanceOn, maintenanceResponse } from "@/lib/access/shared/maintenance";
 import { HEALTH_PATH, healthResponse } from "@/lib/observability/shared/health";
+import { ServerTiming, withServerTiming } from "@/lib/observability/shared/serverTiming";
 import { observeDeployVersion } from "@/lib/activity/deployVersion";
 import { primeActivityKillSwitch } from "@/lib/activity/killSwitch";
 import {
@@ -73,20 +74,27 @@ function routeTierIndexFor(tenant: TenantConfig): RouteTierIndexV1 {
  * appended after the branch has read or written any edge cache.
  */
 export const onRequest = defineMiddleware(async (context, next) => {
+  // An in-process rewrite re-enters this middleware with the same locals; the outer pass owns
+  // the recorder and the header.
+  const outer = !context.locals.serverTiming;
+  const timing = context.locals.serverTiming ?? new ServerTiming();
+  context.locals.serverTiming = timing;
   const seen: { cdnForwarded: boolean; assetBasePath?: string } = { cdnForwarded: false };
-  const response = await serveRequest(context, next, seen);
+  const response = await serveRequest(context, next, seen, timing);
   const { scopePreviewPinnedImageUrls } = await import("@/lib/assets/preview-pinned-image-urls");
   const scoped = await scopePreviewPinnedImageUrls(response, context.locals.apiBasePath ?? seen.assetBasePath ?? "");
-  return withVisitorRegionCookie(
+  const finished = withVisitorRegionCookie(
     scoped,
     visitorRegionFor(context.request, { cdnForwarded: seen.cdnForwarded, dev: import.meta.env.DEV }),
   );
+  return outer ? withServerTiming(finished, timing) : finished;
 });
 
 async function serveRequest(
   context: APIContext,
   next: MiddlewareNext,
   seen: { cdnForwarded: boolean; assetBasePath?: string },
+  timing: ServerTiming,
 ): Promise<Response> {
   const { request, locals } = context;
   const url = new URL(request.url);
@@ -137,6 +145,16 @@ async function serveRequest(
   const crossSite = crossSiteFormRefusal(request, origin);
   if (crossSite) return crossSite;
 
+  // The canonical TEST sample GET signs server catalog facts without shopper state.
+  const sampleHandoff = new URL(SAMPLE_CART_HANDOFF_URL);
+  if (request.method === "GET" && !cdn && url.origin === sampleHandoff.origin &&
+      host === sampleHandoff.host && url.pathname === sampleHandoff.pathname) {
+    const { GET } = await import("@/pages/api/commerce/checkout-handoff");
+    const response = await GET(context);
+    applySecurityHeaders(response.headers);
+    return response;
+  }
+
   // Demo access gate for named hosts (DEMO_GATE_HOSTS). Two modes, switched by
   // DEMO_GATE_MODE:
   //   "password" (default) — interim Basic-Auth gate, enforced HERE (host-level,
@@ -158,10 +176,12 @@ async function serveRequest(
   // Host first; if the host owns no tenant, a leading /<domain>/ path segment
   // selects one (DNS-free tenant selection on localhost/preview). The resolver
   // is KV-backed in prod (many-tenant) and static in plain dev.
-  const resolver = await getTenantResolver();
-  const { tenant, basePath, renderPath } = cdn
-    ? await resolveCdnForwardRouting(cdn, url.pathname, resolver)
-    : await resolveTenantRouting(host, url.pathname, resolver);
+  const { tenant, basePath, renderPath } = await timing.time("tenant", async () => {
+    const resolver = await getTenantResolver();
+    return cdn
+      ? await resolveCdnForwardRouting(cdn, url.pathname, resolver)
+      : await resolveTenantRouting(host, url.pathname, resolver);
+  });
   if (!tenant) {
     return new Response("Unknown host", { status: 404 });
   }
@@ -214,13 +234,14 @@ async function serveRequest(
   let internalContentGrant: InternalContentGrant | undefined;
   if (publication.action !== "fail-closed" && route.requiresAuthorization) {
     const sessionKv = await readKv("SESSION");
-    const decision = await authorizeInternalContentRequest({
+    const coreUrl = await readEnv("TOT_CORE_URL");
+    const decision = await timing.time("internal-auth", () => authorizeInternalContentRequest({
       route,
       sessionStore: sessionKv ? new KvSessionStore(sessionKv) : undefined,
       sessionId: context.cookies.get(SESSION_COOKIE)?.value ?? null,
-      coreUrl: await readEnv("TOT_CORE_URL"),
+      coreUrl,
       mintAssertion: mintOpaqueBrokerAssertion,
-    });
+    }));
     if (decision.allowed) internalContentGrant = decision;
     if (!internalContentGrant) {
       const response = new Response("Not Found", { status: 404 });
@@ -288,7 +309,7 @@ async function serveRequest(
       (capturedRevisionId || renderPath.startsWith("/_a/"))
         ? ((await readR2("PRODUCT_IMAGES")) ?? (await readR2("TENANT_ASSETS")) ?? null)
         : null;
-    const bundled = await tryServeStaticBundle({
+    const bundled = await timing.time("bundle", () => tryServeStaticBundle({
       request,
       url,
       tenant,
@@ -309,7 +330,7 @@ async function serveRequest(
             },
           }
         : {}),
-    });
+    }));
     if (bundled) return bundled;
     const rootLocation = platformStaticRootLocationV1({
       origin,

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

@@ -104,9 +104,10 @@ import {
   resolveIntegrationRenderState,
 } from "@/lib/integrations/integration/renderIntegrationState";
 import { recordActivity } from "@/lib/activity/recordActivity";
+import { timed } from "@/lib/observability/shared/serverTiming";
 import { middlewareRewriteTargetV1 } from "./routeBranch.js";
 import { declaredTenantOrigins } from "@/lib/access/shared/tenantOrigins";
-import { withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
+import { DeclaredTenantConfigUnreadError, withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
 import {
   applyInternalContentResponsePolicy,
   internalContentGrantMatchesPlan,
@@ -226,14 +227,15 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     });
   }
 
-  const publicationSource = await resolvePublicationRuntimeSourceV1({
+  const timing = locals.serverTiming;
+  const publicationSource = await timed(timing, "source", () => resolvePublicationRuntimeSourceV1({
     index: input.routeTierIndex,
     requestPath: input.publicationRequestPath,
     plan: input.publicationRoute,
     channel: channelFromEnv(customization.env),
     store: kv ? { get: (key) => kv.get(key) } : undefined,
     bucket: input.publicationBucket,
-  });
+  }));
   if (publicationSource.status === "unavailable") {
     const response = new Response("Not Found", {
       status: 404,
@@ -264,12 +266,26 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // features). Everything below — static bundle, notices, gates, features,
   // capabilities — reads this, never the bare record. A candidate-pinned render
   // takes the candidate version's declaration, so a reviewer sees the notices the
-  // change under review declares.
-  const tenant = await withDeclaredTenantConfig(
-    tenantRecord,
-    kv ? (key: string) => kv.get(key) : async () => null,
-    { env: customization.env, ...(candidatePin ? { pinnedVersionId: candidatePin.versionId } : {}) },
-  );
+  // change under review declares. A declaration that cannot be read refuses the
+  // render: the store's compliance is unknown, and its gates and notices with it.
+  let tenant: TenantConfig;
+  try {
+    tenant = await timed(timing, "config", () => withDeclaredTenantConfig(
+      tenantRecord,
+      kv ? (key: string) => kv.get(key) : async () => null,
+      { env: customization.env, ...(candidatePin ? { pinnedVersionId: candidatePin.versionId } : {}) },
+    ));
+  } catch (err) {
+    if (!(err instanceof DeclaredTenantConfigUnreadError)) throw err;
+    console.error(err.message);
+    const response = new Response("Service Unavailable", {
+      status: 503,
+      headers: { "Cache-Control": "private, no-store", "Retry-After": "30" },
+    });
+    applySecurityHeaders(response.headers);
+    if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
+    return response;
+  }
   // Request-scoped read memo: every content read resolves the same pointer and
   // version manifest, and a catalog render reads one artifact per catalog file.
   const kvReads = new Map<string, Promise<string | null>>();
@@ -351,12 +367,18 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     secret: previewSecret,
     nowSeconds,
   });
-  const capturedRevisionId = candidatePin?.versionId ?? cookieRevision;
+  // The shared preview sets no version cookie, yet its documents name `/_a/` captures of the
+  // version the preview channel serves (capture overlay); those resolve against that version.
+  const sharedPreviewRevision = !candidatePin && !cookieRevision && customization.env === "test" &&
+    renderPath.startsWith("/_a/")
+    ? (await resolveServableChannelVersion(kvGet, tenant.tenant_id, "preview")).versionId
+    : null;
+  const capturedRevisionId = candidatePin?.versionId ?? cookieRevision ?? sharedPreviewRevision;
   const originalsBucket =
     (capturedRevisionId || renderPath.startsWith("/_a/"))
       ? ((await readR2("PRODUCT_IMAGES")) ?? (await readR2("TENANT_ASSETS")) ?? null)
       : null;
-  const bundled = publicationSource.status === "legacy-root" ? await tryServeStaticBundle({
+  const bundled = publicationSource.status === "legacy-root" ? await timed(timing, "bundle", () => tryServeStaticBundle({
     request,
     url,
     tenant,
@@ -376,7 +398,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
           },
         }
       : {}),
-  }) : null;
+  })) : null;
   if (bundled) return bundled;
 
   // ---- Tenant-local integration materialization (ext-kernel-09) --------------
@@ -496,10 +518,10 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     !candidatePin &&
     !draftCookie &&
     !isInternalPublication &&
-    isCacheablePath(url.pathname, url.searchParams);
+    isCacheablePath(url.pathname);
   let pageKey: Request | null = null;
   if (pageCacheEligible && cache && kv) {
-    const version = await readCacheVersion(kv, tenant.tenant_id);
+    const version = await timed(timing, "page-cache", () => 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).
@@ -514,7 +536,9 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
       locals.integrationCsp?.planRevision,
       publicationSource.status === "selected" ? publicationSource.cacheScope : undefined,
     );
-    const hit = await getCachedPage(cache, pageKey);
+    const key = pageKey;
+    const hit = await timed(timing, "page-cache", () => getCachedPage(cache, key));
+    timing?.note("cache", hit ? "hit" : "miss");
     // 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.
@@ -544,7 +568,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // below still run).
   if (kv && !candidatePin) {
     const channel = channelFromEnv(customization.env);
-    await resolveServableChannelVersion(kvGet, tenant.tenant_id, channel, ({ versionId }) => {
+    await timed(timing, "channel", () => resolveServableChannelVersion(kvGet, tenant.tenant_id, channel, ({ versionId }) => {
       recordActivity({
         action: "preview.build.requested",
         actor: { kind: "system", id: "storefront" },
@@ -553,7 +577,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
         scope: { tenantId: tenant.tenant_id },
         payload: { args: { changeId: versionId } },
       });
-    }).catch(() => {
+    })).catch(() => {
       /* fail-open: self-heal detection never breaks the request */
     });
   }
@@ -570,7 +594,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     draftClaims && draftClaims.tenantId === tenant.tenant_id ? draftClaims : null;
 
   let theme = mergeTheme(referenceTheme, tenant.theme_tokens);
-  const publishedTheme = await readRuntimeArtifact(themeArtifactPath(tenant.tenant_id));
+  const publishedTheme = await timed(timing, "artifacts", () => readRuntimeArtifact(themeArtifactPath(tenant.tenant_id)));
   if (publishedTheme) {
     try {
       theme = mergeTheme(theme, JSON.parse(publishedTheme) as DeepPartial<ThemeTokens>);
@@ -596,7 +620,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // 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 readRuntimeArtifact(capabilitiesArtifactPath(tenant.tenant_id));
+  const publishedCapsRaw = await timed(timing, "artifacts", () => readRuntimeArtifact(capabilitiesArtifactPath(tenant.tenant_id)));
   if (publishedCapsRaw) {
     try {
       publishedCaps = JSON.parse(publishedCapsRaw) as Partial<CapabilityConfig>;
@@ -612,7 +636,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // 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 readRuntimeArtifact(embedsArtifactPath(tenant.tenant_id));
+  const publishedEmbedsRaw = await timed(timing, "artifacts", () => readRuntimeArtifact(embedsArtifactPath(tenant.tenant_id)));
   if (publishedEmbedsRaw) {
     try {
       const parsed = JSON.parse(publishedEmbedsRaw);
@@ -648,7 +672,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // loader + signed add-to-cart, and the CSP additions below.
   const commerce =
     locals.features.catalog && capabilities.cartCheckout.enabled
-      ? await resolveTenantCommerce(tenant)
+      ? await timed(timing, "commerce", () => resolveTenantCommerce(tenant))
       : null;
   locals.commerce = commerce ?? undefined;
   // Developer-draft content overlay — serves the AI-edited artifacts to the draft
@@ -666,7 +690,8 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // are read through the SAME content source just resolved, so they follow the
   // request's selected version exactly as pages and the blog do. Only the control
   // plane supplies the D1 projection; the public branch never reads D1.
-  locals.tot = await createToTClient(tenant, await input.readCatalogD1?.(), locals.content);
+  locals.tot = await timed(timing, "catalog", async () =>
+    createToTClient(tenant, await input.readCatalogD1?.(), locals.content));
   locals.themeStyle = themeToCssVars(theme);
   locals.canonicalBase = canonicalBase;
   locals.customizationEnv = customization.env;
@@ -733,9 +758,9 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     // request. Rewriting there discards the route it already chose.
     routePattern: context.routePattern,
   });
-  let response = rewriteTarget !== undefined
-    ? await next(rewriteTarget)
-    : await next();
+  let response = await timed(timing, "render", () => rewriteTarget !== undefined
+    ? next(rewriteTarget)
+    : next());
 
   // A nested pass of this middleware (an in-process `rewrite()`) already decorated
   // and nonce-stamped the response. Serve it verbatim: decorating again would inject
@@ -869,7 +894,8 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     );
     // 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);
+    const key = pageKey;
+    await timed(timing, "page-cache", () => putCachedPage(cache, key, 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

package/apps/storefront/src/pages/[...slug].astro

@@ -40,6 +40,9 @@ if (
 // dir, so the pages live under `/style-guide/…` and we rewrite the underscored URL
 // onto them, under the same tenant prefix. These are noindex + sitemap-excluded and
 // never reskin the live site.
+// Its query, like the `__preview` flag below, only matters to a Worker render: the
+// static copy of a page is the published, non-preview render.
+export const STATIC_QUERY = "render-only";
 const styleGuideTarget = styleGuideAliasRewrite(basePath, slug, Astro.url.search);
 if (styleGuideTarget !== undefined) {
   return Astro.rewrite(styleGuideTarget);

package/apps/storefront/src/pages/api/commerce/final-cart-authorization.ts

@@ -2,7 +2,7 @@
 import type { APIContext } from "astro";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify, type JSONWebKeySet } from "jose";
 import {
-  commerceTenantId, totalsMatch, canonicalJson, deriveProductProfile,
+  commerceTenantId, totalsMatch, canonicalJson, shippingMinorFor,
   type CallerToken, type CatalogProduct, type CommerceEvidence, type CommerceEvidenceProvenance,
   type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
@@ -12,14 +12,20 @@ import { evaluateFinalCart, type SeamView } from "@/lib/checkout/commerce/finalC
 import { d1CommerceRunner, reserveAllocation } from "@/lib/inventory/allocations.js";
 import { readMirrorStock } from "@/lib/inventory/mirrorStock.js";
 import { admissionMatches, readCommerceAdmission, admissionSnapshotStatement } from "@/lib/checkout/commerce/commerceAdmission.js";
-import { isRegulatedTenant } from "@/lib/compliance/enforcement.js";
-import { POST as compliancePreflight } from "../compliance/preflight.js";
-import { resolveAdminTargetTenant } from "@/config/adminTargetTenant";
-import { withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
+import { evaluatePreflight } from "../compliance/preflight.js";
+import {
+  admitSharedStoreTenant, testStoreEvidencePolicy, SHARED_STORE_POLICY_REVISION, SHARED_STORE_POLICY_SOURCE,
+  SHARED_STORE_VERIFICATION_SOURCE, type SharedStoreEvidencePolicy,
+} from "@/lib/checkout/commerce/sharedStoreAdmission.js";
+import { readCheckoutRequirements } from "@/lib/checkout/commerce/checkoutRequirements.js";
+import { DeclaredTenantConfigUnreadError, withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
+import { resolveStoreCurrency } from "@tot/public-runtime/declared-tenant-config";
 import { createContentProvider } from "@/lib/content/storyblok/provider";
 import { createToTClient } from "@/lib/catalog/tot/ToTClient";
 export const prerender = false;
 const HEX = /^[a-f0-9]{64}$/;
+/** The shopper's verification correlation handle, as the signed `verification` cart option carries it. */
+const VERIFICATION_REF = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,199}$/;
 function json(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" } });
 }
@@ -46,8 +52,10 @@ function readSnapshot(value: unknown): CommerceProviderCartSnapshot | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const v = value as Record<string, unknown>;
   const allowed = ["provider", "providerCartId", "providerCartDigest", "tenantId", "stage", "currency", "lines", "totals", "destinationDigest", "destination"];
-  if (Object.keys(v).some(k => !allowed.includes(k) && k !== "expectedAuthorizationId") || allowed.some(k => !(k in v))) return null;
+  const optional = ["expectedAuthorizationId", "verificationRef"];
+  if (Object.keys(v).some(k => !allowed.includes(k) && !optional.includes(k)) || allowed.some(k => !(k in v))) return null;
   if ("expectedAuthorizationId" in v && (typeof v.expectedAuthorizationId !== "string" || !/^[a-z0-9][a-z0-9-]{0,80}$/.test(v.expectedAuthorizationId))) return null;
+  if ("verificationRef" in v && (typeof v.verificationRef !== "string" || !VERIFICATION_REF.test(v.verificationRef))) return null;
   if (v.provider !== "foxycart" || typeof v.providerCartId !== "string" || !/^[a-zA-Z0-9._:-]{1,128}$/.test(v.providerCartId) ||
       typeof v.providerCartDigest !== "string" || !HEX.test(v.providerCartDigest) || typeof v.destinationDigest !== "string" || !HEX.test(v.destinationDigest) ||
       typeof v.tenantId !== "string" || !["preview", "publication"].includes(String(v.stage)) || typeof v.currency !== "string" || !/^[A-Z]{3}$/.test(v.currency) ||
@@ -64,19 +72,46 @@ function readSnapshot(value: unknown): CommerceProviderCartSnapshot | null {
   if (!totalsMatch(snapshot.totals) || snapshot.lines.reduce((sum, line) => sum + line.quantity * line.unitMinor, 0) !== snapshot.totals.subtotalMinor) return null;
   return snapshot;
 }
-async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot, products: readonly CatalogProduct[]): Promise<SeamView> {
-  const response = await compliancePreflight({
-    request: new Request("https://checkout.invalid/api/compliance/preflight", {
-      method: "POST", headers: { "content-type": "application/json" },
-      body: JSON.stringify({ lines: snapshot.lines.map(line => ({ handle: products.find(p => p.variants.some(v => v.sku === line.sku))!.handle, sku: line.sku, quantity: line.quantity })), destination: snapshot.destination }),
-    }), locals: { tenant: context.locals.tenant, tot: context.locals.tot },
-  } as APIContext);
+/**
+ * The compliance seam under the shared test store's policy. When verification is required the
+ * cart's verification ref goes to preflight, whose live provider re-reads its real status
+ * server-side; `verified` is true only when that read satisfied the requirement.
+ */
+async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot, selected: ReadonlyMap<string, CatalogProduct>, policy: SharedStoreEvidencePolicy): Promise<SeamView & { verified: boolean }> {
+  if (policy.rules === "off" && policy.verification === "not-required") return { status: "clear", verified: false };
+  const products = [...selected.values()];
   try {
-    const body = await response.json() as { decision?: { status?: string; failedClosed?: boolean; blocks?: { code?: string }[] } };
-    if (!body.decision) return { status: "absent" };
-    if (body.decision.status === "clear") return { status: "clear" };
-    return { status: "blocked", failedClosed: body.decision.failedClosed === true, codes: body.decision.blocks?.map(b => b.code ?? "") };
-  } catch { return { status: "absent" }; }
+    const { decision } = await evaluatePreflight({ locals: { tenant: context.locals.tenant, tot: {
+      getProductByHandle: async (handle: string) => selected.get(handle) ?? null,
+    } } } as APIContext, {
+      lines: snapshot.lines.map(line => ({ handle: products.find(p => p.variants.some(v => v.sku === line.sku))!.handle, sku: line.sku, quantity: line.quantity })),
+      destination: snapshot.destination,
+      ...(policy.verification === "required" && snapshot.verificationRef ? { verificationRef: snapshot.verificationRef } : {}),
+    }, { verification: policy.verification, rules: policy.rules });
+    const verified = policy.verification === "required" && decision.requirements.ageVerification === "satisfied";
+    const blocks = decision.blocks;
+    if (blocks.length === 0) return { status: "clear", verified };
+    const flavors = [...new Set(blocks.flatMap(block => block.code === "flavored_prohibited" ? block.flavors ?? [] : []))];
+    return { status: "blocked", verified, failedClosed: blocks.some(block => block.failedClosed === true), codes: blocks.map(block => block.code),
+      ...(flavors.length ? { flavors } : {}) };
+  } catch { return { status: "absent", verified: false }; }
+}
+function fullCartProduct(value: unknown, handle: string, scope: string): value is CatalogProduct {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const product = value as CatalogProduct;
+  return product.handle === handle && product.tenant_id === scope && typeof product.id === "string" && !!product.id &&
+    product.status === "active" && (product.visibility === undefined || product.visibility === "public") &&
+    typeof product.title === "string" && (product.product_type === undefined || typeof product.product_type === "string") &&
+    Array.isArray(product.tags) && product.tags.every(tag => typeof tag === "string") &&
+    Array.isArray(product.metafields) && product.metafields.every(field => field && typeof field === "object" && !Array.isArray(field) &&
+      typeof field.namespace === "string" && typeof field.key === "string" && typeof field.value === "string") &&
+    Array.isArray(product.variants) && product.variants.length > 0 && product.variants.every(variant => variant && typeof variant === "object" && !Array.isArray(variant) &&
+      variant.tenant_id === scope && variant.product_id === product.id && typeof variant.id === "string" && !!variant.id &&
+      (variant.sku === undefined || typeof variant.sku === "string") && Number.isFinite(variant.price) && variant.price >= 0 &&
+      typeof variant.currency === "string" && /^[A-Z]{3}$/.test(variant.currency) &&
+      variant.option_values && typeof variant.option_values === "object" && !Array.isArray(variant.option_values) &&
+      Object.values(variant.option_values).every(option => typeof option === "string") &&
+      variant.inventory && typeof variant.inventory === "object" && !Array.isArray(variant.inventory) && typeof variant.inventory.available === "boolean");
 }
 export async function POST(context: APIContext): Promise<Response> {
   if (Number(context.request.headers.get("content-length") ?? 0) > 65536) return deny("malformed-request");
@@ -102,28 +137,58 @@ export async function POST(context: APIContext): Promise<Response> {
     token = { scheme: "asymmetric-jwks", signatureValid: true, kid: header.kid, issuer: payload.iss ?? "", audience,
       expiresAt: new Date(payload.exp * 1000).toISOString(), jti: payload.jti ?? "", tenantId: snapshot.tenantId, stage: snapshot.stage };
   } catch { return deny("signature", 401); }
-  const allowedTenants = list(await readEnv("COMMERCE_TENANT_ALLOWLIST"));
-  if (!allowedTenants || !allowedTenants.includes(snapshot.tenantId)) return deny("tenant", 401);
-  const registered = await resolveAdminTargetTenant(snapshot.tenantId);
-  if (!registered || commerceTenantId(registered) !== snapshot.tenantId) return deny("tenant-unregistered", 401);
+  const admission = await admitSharedStoreTenant(snapshot.tenantId);
+  if (!admission.ok) return deny(admission.finding, 401);
+  const registered = admission.tenant;
   const kv = await readKv("TENANT_CACHE");
   const kvGet = async (key: string): Promise<string | null> => kv ? kv.get(key) : null;
   const contentEnv = snapshot.stage === "publication" ? "live" : "test";
-  const tenant = await withDeclaredTenantConfig(registered, kvGet, { env: contentEnv });
+  let tenant: TenantConfig;
+  try { tenant = await withDeclaredTenantConfig(registered, kvGet, { env: contentEnv }); } catch (err) {
+    if (err instanceof DeclaredTenantConfigUnreadError) return deny("config-unreadable", 503);
+    throw err;
+  }
   const content = createContentProvider(tenant, { get: kvGet, env: contentEnv });
   const tot = await createToTClient(tenant, await readD1("CATALOG_DB"), content);
   const authorityContext = { ...context, locals: { ...context.locals, tenant, tot, content } } as APIContext;
   const { tenantId, stage, currency, totals, destinationDigest } = snapshot;
   const lines = [...snapshot.lines].sort((a, b) => a.sku.localeCompare(b.sku) || a.unitMinor - b.unitMinor || a.quantity - b.quantity);
   if (snapshot.providerCartDigest !== await digest(canonicalJson({ tenantId, stage, currency, lines, totals, destinationDigest }))) return deny("provider-cart-digest");
-  let products: CatalogProduct[];
-  try { products = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
+  let listing: CatalogProduct[];
+  try { listing = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
+  if (!Array.isArray(listing)) return deny("catalog-unavailable", 503);
+  const selected = new Map<string, CatalogProduct>();
+  if (snapshot.currency !== resolveStoreCurrency(tenant.currency)) return deny("catalog-cart-mismatch");
   for (const line of snapshot.lines) {
-    const matches = products.flatMap(product => product.status === "active" && (!product.visibility || product.visibility === "public") && product.tenant_id === tenant.tot_data_scope
-      ? product.variants.filter(v => v.sku === line.sku).map(variant => ({ product, variant })) : []);
+    const matches = listing.flatMap(product => product && product.status === "active" && (!product.visibility || product.visibility === "public") && product.tenant_id === tenant.tot_data_scope && Array.isArray(product.variants)
+      ? product.variants.filter(v => v && v.sku === line.sku).map(variant => ({ product, variant })) : []);
+    if (matches.length !== 1) return deny("catalog-cart-mismatch");
+    const match = matches[0]!;
+    const handle = match.product.handle;
+    if (typeof handle !== "string" || !handle) return deny("catalog-cart-mismatch");
+    if (!selected.has(handle)) {
+      let detail: CatalogProduct | null;
+      try { detail = await tot.getProductByHandle(handle); } catch { return deny("catalog-unavailable", 503); }
+      if (!fullCartProduct(detail, handle, tenant.tot_data_scope)) return deny("catalog-cart-mismatch");
+      selected.set(handle, detail);
+    }
+    const detail = selected.get(handle)!;
+    if (detail.id !== match.product.id) return deny("catalog-cart-mismatch");
+    const variants = detail.variants.filter(variant => variant.sku === line.sku);
+    if (variants.length !== 1 || variants[0]!.id !== match.variant.id) return deny("catalog-cart-mismatch");
+    const variant = variants[0]!;
     const digits = new Intl.NumberFormat("en", { style: "currency", currency: snapshot.currency }).resolvedOptions().maximumFractionDigits ?? 2;
-    const scaled = (matches[0]?.variant.price ?? -1) * 10 ** digits;
-    if (matches.length !== 1 || !matches[0]!.variant.inventory.available || matches[0]!.variant.currency !== snapshot.currency || Math.abs(scaled - Math.round(scaled)) > 0.000001 || Math.round(scaled) !== line.unitMinor) return deny("catalog-cart-mismatch");
+    const scaled = variant.price * 10 ** digits;
+    if (!variant.inventory.available || variant.currency !== snapshot.currency || Math.abs(scaled - Math.round(scaled)) > 0.000001 || Math.round(scaled) !== line.unitMinor) return deny("catalog-cart-mismatch");
+  }
+  const products = [...selected.values()];
+  if (snapshot.lines.some(line => products.flatMap(product => product.variants.filter(variant => variant.sku === line.sku)).length !== 1)) return deny("catalog-cart-mismatch");
+  // Shipping is re-derived from the store's own declaration, never from the cart: a cart that
+  // dropped, replayed or altered its signed `shipping_policy` option was charged another amount.
+  if (tenant.shipping) {
+    let owed: number;
+    try { owed = shippingMinorFor(tenant.shipping, snapshot.currency, snapshot.totals.subtotalMinor); } catch { return deny("shipping-unavailable"); }
+    if (snapshot.totals.shippingMinor !== owed) return deny("shipping-changed");
   }
   const database = await readD1("STOREFRONT_APPS_DB");
   if (!database) return deny("store-unconfigured", 503);
@@ -142,35 +207,40 @@ export async function POST(context: APIContext): Promise<Response> {
   const existing = prior ? await readCommerceAdmission(queryable, snapshot.tenantId, snapshot.stage, prior.authorization_id) : null;
   if (prior && (!existing || existing.expiresAt <= now)) return deny("admission-expired");
   if (existing && !admissionMatches(existing, snapshot)) return deny("provider-cart-changed");
-  const policy = tenant.commerce?.authorityPolicy;
-  const testPolicy = policy?.purpose === "synthetic-nonbillable" && typeof policy.revision === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(policy.revision) &&
-    Number.isFinite(Date.parse(policy.expiresAt)) && policy.expiresAt > now && await readEnv("COMMERCE_DEMO_CHECKOUT_TIER") === "test" &&
-    tenant.commerce?.checkout?.storeSubDomain === "tot-preview" && tenant.commerce.checkout.mode === "signed" &&
-    ["verification", "tax", "risk"].every(field => ["required", "not-required"].includes(policy.requirements?.[field as "verification" | "tax" | "risk"]));
-  const regulated = isRegulatedTenant(tenant) || !!tenant.compliance?.pactAct || !!tenant.compliance?.exciseTax ||
-    snapshot.lines.some(line => products.some(p => p.variants.some(v => v.sku === line.sku && ["ends", "e-liquid", "other-nicotine"].includes(deriveProductProfile(p, v).category))));
-  if (testPolicy && regulated && (policy.requirements.verification === "not-required" || policy.requirements.tax === "not-required")) return deny("authority-policy-regulated");
+  const requirements = await readCheckoutRequirements(tenant.tenant_id, contentEnv);
+  if (!requirements) return deny("checkout-requirements-unreadable", 503);
+  const policy = testStoreEvidencePolicy(requirements);
   const authorities = [];
   for (const sku of new Set(snapshot.lines.map(line => line.sku))) {
     authorities.push(await readMirrorStock(queryable, { tenantId: snapshot.tenantId, stage: snapshot.stage, sku, locationId: "unspecified", now, maxAgeMs: 15 * 60_000 }));
   }
   const stockExpiry = Math.min(...authorities.flatMap(authority => authority ? [Date.parse(authority.asOf) + 15 * 60_000] : []));
   const evidence: CommerceEvidence = { verification: "absent", tax: "absent", risk: "absent", stock: "fresh" };
-  const expiresAt = existing?.expiresAt ?? new Date(Math.min(Date.now() + 5 * 60_000, stockExpiry, testPolicy ? Date.parse(policy.expiresAt) : Infinity)).toISOString();
+  const expiresAt = existing?.expiresAt ?? new Date(Math.min(Date.now() + 5 * 60_000, stockExpiry)).toISOString();
   const provenance = {} as CommerceEvidenceProvenance;
   for (const field of ["verification", "tax", "risk"] as const) {
-    if (testPolicy && policy.requirements?.[field] === "not-required") {
+    if (policy[field] === "not-required") {
       evidence[field] = "not-required";
-      provenance[field] = { requirement: "not-required", state: "not-required", source: "declared-synthetic-policy", policyRevision: policy.revision, expiresAt };
+      provenance[field] = { requirement: "not-required", state: "not-required", source: SHARED_STORE_POLICY_SOURCE, policyRevision: SHARED_STORE_POLICY_REVISION, expiresAt };
     }
   }
   provenance.stock = { requirement: "required", state: "satisfied", source: "tenant-inventory-movements", policyRevision: "mirror-v1", expiresAt };
   const presented: FinalCartBinding = { tenantId: snapshot.tenantId, stage: snapshot.stage, currency: snapshot.currency, lines: snapshot.lines,
     destinationDigest: snapshot.destinationDigest, verificationExpiresAt: expiresAt, taxExpiresAt: expiresAt };
+  const seamView = await seam(authorityContext, snapshot, selected, policy);
+  if (policy.verification === "required" && seamView.verified) {
+    evidence.verification = "fresh";
+    provenance.verification = { requirement: "required", state: "satisfied", source: SHARED_STORE_VERIFICATION_SOURCE, policyRevision: SHARED_STORE_POLICY_REVISION, expiresAt };
+  }
   const decision = await evaluateFinalCart({ now, routedTenantId: commerceTenantId(tenant), quoted: presented, presented, evidence,
-    seam: await seam(authorityContext, snapshot, products), catalogAvailable: true, browserConfirmed: false, token,
+    seam: seamView, catalogAvailable: true, browserConfirmed: false, token,
     trustedIssuers: issuers, expectedAudience: audience, activeKids, authorities });
-  if (!decision.ok) return deny(decision.finding, 409, decision.owner);
+  if (!decision.ok) {
+    if (decision.finding === "verification-refused:flavored_prohibited" && seamView.flavors) {
+      return json({ ok: false, finding: decision.finding, flavors: seamView.flavors }, 409);
+    }
+    return deny(decision.finding, 409, decision.owner);
+  }
   const authorizationId = existing?.authorizationId ?? `a${crypto.randomUUID()}`;
   // Retries of the same verified provider cart share one reservation, including concurrent callbacks.
   const cartDigest = existing?.cartDigest ?? await digest(`commerce-provider-cart-v1\n${snapshot.providerCartId}\n${snapshot.providerCartDigest}`);