@tokenoftrust/storefront-runner 2.2.90 → 2.2.91

package/apps/storefront/src/config/declaredTenantConfig.ts

@@ -80,15 +80,21 @@ export async function versionDeclaredTenantConfig(
   }
 }
 
-/** The tenant as it renders in `env`: its record with every declaration applied. */
+/**
+ * The tenant as it renders: its record with every declaration applied. A render
+ * pinned to one version (a candidate under review) takes that version's
+ * declaration; otherwise the environment's channel supplies it.
+ */
 export async function withDeclaredTenantConfig(
   tenant: TenantConfig,
   kvGet: (key: string) => Promise<string | null>,
-  env: CustomizationEnv,
+  source: { env: CustomizationEnv; pinnedVersionId?: string },
 ): Promise<TenantConfig> {
   const fromCheckout = applyDeclaredTenantConfig(tenant, checkoutDeclaredTenantConfig(tenant.tenant_id));
   return applyDeclaredTenantConfig(
     fromCheckout,
-    await publishedDeclaredTenantConfig(kvGet, tenant.tenant_id, env),
+    source.pinnedVersionId
+      ? await versionDeclaredTenantConfig(kvGet, tenant.tenant_id, source.pinnedVersionId)
+      : await publishedDeclaredTenantConfig(kvGet, tenant.tenant_id, source.env),
   );
 }

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

@@ -235,11 +235,13 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // The tenant as it renders in THIS environment: its record with the declared
   // `.tot/config.json` fields applied (compliance, siteType, capabilities,
   // features). Everything below — static bundle, notices, gates, features,
-  // capabilities — reads this, never the bare record.
+  // 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,
-    customization.env,
+    { env: customization.env, ...(candidatePin ? { pinnedVersionId: candidatePin.versionId } : {}) },
   );
   const publicationTimestamp = publicationSource.status === "selected"
     ? publicationSource.publicationTimestamp
@@ -752,7 +754,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // 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
+  // via its published embeds.json. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.90",
+  "version": "2.2.91",
   "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/cli/src/declared-config.mjs

@@ -0,0 +1,78 @@
+/**
+ * The `.tot/config.json` keys the platform reads, and the refusal of everything
+ * else. Shared by `tot validate` (src/validate.mjs) and the monorepo/dev-loop
+ * validator (scripts/tenant/validate.mjs), so both refuse the same keys.
+ *
+ * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
+ * to npm on its own); test/declared-config-parity.test.mjs pins the two together, so
+ * a field the platform honors can never be refused here, and a key no surface reads
+ * can never pass. Dependency-free: the storefront runner copies this file as-is.
+ */
+
+export const TOT_CONFIG_KEYS = [
+  "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
+  "siteType", "compliance", "capabilities", "features",
+];
+// Keys other tooling has written that the platform does NOT read, with the key it does.
+const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
+export const COMPLIANCE_KEYS = [
+  "ruleProfile", "minAge", "nicotineWarning", "shippingRestriction", "pactAct",
+  "adultSignature", "prop65", "purchaseLimit", "stateEligibility", "exciseTax",
+];
+export const FEATURE_KEYS = [
+  "catalog", "productSearch", "savedItems", "quickView", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
+];
+export const SITE_TYPES = ["commerce", "marketing"];
+
+const ERROR = "error";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
+function mk(level, rule, file, message, fix) {
+  return { level, rule, file, message, fix };
+}
+
+/**
+ * Refuse what the platform would silently ignore: an unknown top-level key, an
+ * unknown `compliance`/`features` key, or a declared field of the wrong shape. Each
+ * one passes JSON parsing and renders nothing — on a regulated store that is a
+ * mandated notice that never appears.
+ * @param {Record<string, any>} config parsed `.tot/config.json` (an object)
+ * @param {string} [file]
+ * @returns {Finding[]}
+ */
+export function validateDeclaredConfig(config, file = ".tot/config.json") {
+  const out = [];
+  for (const key of Object.keys(config)) {
+    if (!TOT_CONFIG_KEYS.includes(key)) {
+      const renamed = RENAMED_CONFIG_KEYS[/** @type {keyof typeof RENAMED_CONFIG_KEYS} */ (key)];
+      out.push(mk(ERROR, "config-unknown-key", file,
+        `\`${key}\` is not a .tot/config.json key — the platform never reads it`,
+        renamed ? `use \`${renamed}\`` : `known keys: ${TOT_CONFIG_KEYS.join(", ")}`));
+    }
+  }
+  if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
+    out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
+  }
+  /** @type {Array<[string, string[]]>} */
+  const objectFields = [["compliance", COMPLIANCE_KEYS], ["features", FEATURE_KEYS]];
+  for (const [field, known] of objectFields) {
+    const value = config[field];
+    if (value === undefined) continue;
+    if (!isObject(value)) {
+      out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
+      continue;
+    }
+    for (const key of Object.keys(value)) {
+      if (!known.includes(key)) {
+        out.push(mk(ERROR, `config-${field}-unknown-key`, `${file} ${field}`,
+          `\`${field}.${key}\` is not a ${field} key — nothing renders from it`,
+          `known keys: ${known.join(", ")}`));
+      }
+    }
+  }
+  if (config.capabilities !== undefined && !isObject(config.capabilities)) {
+    out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
+  }
+  return out;
+}

package/packages/public-runtime/src/csp.ts

@@ -103,7 +103,7 @@ export const STOREFRONT_CSP_ALLOWLIST = {
 
 /**
  * Curated catalog of known third-party embeds a tenant may opt into. Keyed by a
- * stable provider slug the tenant lists in `.tot/config.json` `embeds:`; the
+ * stable provider slug the tenant lists in its `embeds.json`; the
  * platform (never the tenant) owns the exact origins each provider needs, so a
  * tenant can enable "pipedrive" without ever hand-writing a CSP origin — and a
  * novel provider requires a reviewed catalog entry here, not a config edit.
@@ -170,7 +170,7 @@ export interface EmbedCspAdditions {
  * CSP additions for the third-party embeds ACTUALLY rendered on this page.
  *
  * An origin is added only when BOTH hold: (1) the tenant opted the provider in
- * via `.tot/config.json` `embeds:` (audit trail + platform review of novel
+ * via its `embeds.json` (audit trail + platform review of novel
  * providers), and (2) the provider's marker appears in the rendered HTML (so a
  * page that doesn't embed the form never carries the origin). This keeps the
  * strict policy tenant- AND page-scoped — never a blanket global relaxation.

package/packages/public-runtime/src/tenant.ts

@@ -503,10 +503,16 @@ export interface TenantConfig {
    * the pages that actually contain it (see `embedCspAdditions`). A provider not
    * in the catalog needs a reviewed platform addition, not a config edit — so
    * this stays an auditable allow-list, never an escape hatch to arbitrary hosts.
-   * Declared in the tenant's platform config alongside `siteType`/`capabilities`.
+   * The platform default comes from tenant-embed-defaults.mjs; a tenant opts in
+   * itself by committing `embeds.json` (see `resolveEffectiveEmbeds`).
    */
   embeds?: string[];
-  /** Regulated-commerce affordances; undefined for unregulated tenants. */
+  /**
+   * Regulated-commerce affordances; undefined for unregulated tenants. A tenant
+   * declares these in its `.tot/config.json`; every render reads them through
+   * `applyDeclaredTenantConfig` (declared-tenant-config.mjs), never off the bare
+   * tenant record alone.
+   */
   compliance?: ComplianceConfig;
   /**
    * Per-tenant newsletter compliance/sender config. Sourced when a digest is

package/scripts/dev/standalone-graft-plan.mjs

@@ -45,8 +45,8 @@ export function standaloneGraftPlan(tenant, mappings) {
   // `.tot/config.json` is never itself one of the declared `mappings` (those map
   // content/public/theme.json) but IS the tenant's own declared platform config
   // — siteType/compliance/capabilities/features (see
-  // apps/storefront/src/config/devTenantSeed.ts TOT_CONFIG_TENANT_FIELDS and
-  // resolver.ts declaredConfigs()) — the same file
+  // packages/public-runtime/src/declared-tenant-config.mjs, applied by
+  // apps/storefront/src/config/declaredTenantConfig.ts) — the same file
   // scripts/tenant/materialize-tenant-content.mjs copies for a Gitea-sourced
   // tenant. Graft it unconditionally so a regulated store's mandated notices
   // resolve from the SAME declared config locally as they would once published.

package/scripts/tenant/validate.mjs

@@ -44,6 +44,7 @@ import {
   workspacePathForTenantRelative,
 } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
+import { validateDeclaredConfig } from "../../packages/cli/src/declared-config.mjs";
 
 /** Catalogued embed slugs a tenant may opt into (mirror of EMBED_PROVIDERS). */
 const KNOWN_EMBED_SLUGS = new Set(KNOWN_EMBEDS.map((p) => p.slug));
@@ -115,6 +116,8 @@ export function validateConfigShape(config, file = ".tot/config.json") {
   if (typeof config.tenant !== "string" || !config.tenant) {
     out.push(mk(ERROR, "config-tenant", file, "`tenant` must be a non-empty string"));
   }
+  // The same refusal `tot validate` applies: a key no surface reads never passes.
+  out.push(...validateDeclaredConfig(config, file));
   if (!Array.isArray(config.mappings)) {
     out.push(mk(ERROR, "config-mappings", file, "`mappings` must be an array", "seed shape: [{workspace,repo,kind}]"));
     return out; // nothing more to check without the array