@tokenoftrust/storefront-runner 4.14.0 → 4.15.0

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

@@ -17,7 +17,8 @@
  */
 import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
 import { withPlatformPolicy } from "@/config/tenants";
-import { TENANT_RECORD_PREFIX } from "@/config/storedTenantRecord";
+import { TENANT_RECORD_PREFIX, getStoredTenantRecord } from "@/config/storedTenantRecord";
+import { mergeStoredTenantRecord } from "@tot/public-runtime/tenant-record-merge";
 
 const DOMAIN_PREFIX = "domain:";
 const TENANT_PREFIX = TENANT_RECORD_PREFIX;
@@ -76,16 +77,25 @@ export class KvTenantResolver implements TenantResolver {
 }
 
 /**
- * Register (or update) a tenant in KV. Idempotent: writes the config blob and a
- * domain->id index entry for each claimed hostname. Pass `makeDefault` to point
- * the unknown-host fallback at this tenant. Call this from onboarding/migration.
+ * Register (or update) a tenant in KV. Idempotent: merges the config into the stored
+ * `tenant:<id>` record (provisioned keys win, stored keys the config does not carry survive;
+ * see `@tot/public-runtime/tenant-record-merge`) and writes a domain->id index entry for each
+ * claimed hostname. The stored record is read uncached. A stored record that is not a JSON
+ * object throws before any write. Pass `makeDefault` to point the unknown-host fallback at
+ * this tenant. Call this from onboarding/migration.
  */
 export async function putTenant(
   kv: KVNamespace,
   config: TenantConfig,
   opts: { makeDefault?: boolean } = {},
 ): Promise<void> {
-  await kv.put(TENANT_PREFIX + config.tenant_id, JSON.stringify(config));
+  const key = TENANT_PREFIX + config.tenant_id;
+  const record = mergeStoredTenantRecord(
+    key,
+    await getStoredTenantRecord(kv, config.tenant_id),
+    config as unknown as Record<string, unknown>,
+  );
+  await kv.put(key, record);
   for (const domain of config.domains) {
     const host = cleanHost(domain);
     if (host) await kv.put(DOMAIN_PREFIX + host, config.tenant_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.14.0",
+  "version": "4.15.0",
   "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/package.json

@@ -26,6 +26,7 @@
     "./svg-sanitize": "./src/svg-sanitize.ts",
     "./incremental-sha256": "./src/incremental-sha256.ts",
     "./image-limits": "./src/image-limits.mjs",
+    "./tenant-record-merge": "./src/tenant-record-merge.mjs",
     "./image-release-gate": "./src/image-release-gate.ts",
     "./pool-asset-headers": "./src/pool-asset-headers.ts",
     "./catalog-files": "./src/catalog-files.ts",

package/packages/public-runtime/src/tenant-record-merge.d.mts

@@ -0,0 +1,9 @@
+export declare function mergeTenantRecord(
+  stored: Record<string, unknown>,
+  provisioned: Record<string, unknown>,
+): Record<string, unknown>;
+export declare function mergeStoredTenantRecord(
+  key: string,
+  storedRaw: string | null | undefined,
+  provisioned: Record<string, unknown>,
+): string;

package/packages/public-runtime/src/tenant-record-merge.mjs

@@ -0,0 +1,68 @@
+/**
+ * Merge a provisioned tenant config into the `tenant:<id>` KV record already stored.
+ *
+ * Provisioners carry only the fields they own. The stored record also holds fields written by
+ * other paths (`storefront.mode`, `addOns.largeImages`), so a provisioner must read the stored
+ * record, merge, and write the result; it never replaces the record wholesale.
+ *
+ * Contract:
+ * - the provisioned config wins for every key it carries;
+ * - plain objects merge recursively; arrays and scalars from the provisioned config replace;
+ * - keys the provisioned config does not carry are preserved;
+ * - `__proto__`, `constructor` and `prototype` keys are dropped at every level;
+ * - no stored record: the provisioned config is written as given;
+ * - a stored value that is not a JSON object (unparseable, array, scalar, empty string) throws,
+ *   naming the key, and the caller writes nothing.
+ *
+ * KV has no transaction. A provisioner that reads, merges and writes while the admin add-ons
+ * switch writes the same record can still lose one of the two writes; the merge narrows that
+ * window to one read-to-write interval and cannot close it.
+ */
+
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {Record<string, unknown>} stored
+ * @param {Record<string, unknown>} provisioned
+ * @returns {Record<string, unknown>}
+ */
+export function mergeTenantRecord(stored, provisioned) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, value] of Object.entries(stored)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    out[key] = value;
+  }
+  for (const [key, value] of Object.entries(provisioned)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    const existing = out[key];
+    out[key] = isPlainObject(value) && isPlainObject(existing) ? mergeTenantRecord(existing, value) : value;
+  }
+  return out;
+}
+
+/**
+ * The JSON to write at `key` for `provisioned`, given the raw stored value (`null` when absent).
+ * @param {string} key
+ * @param {string | null | undefined} storedRaw
+ * @param {Record<string, unknown>} provisioned
+ * @returns {string}
+ */
+export function mergeStoredTenantRecord(key, storedRaw, provisioned) {
+  if (storedRaw === null || storedRaw === undefined) return JSON.stringify(provisioned);
+  let stored;
+  try {
+    stored = JSON.parse(storedRaw);
+  } catch {
+    throw new Error(`stored KV record ${key} is not valid JSON; refusing to overwrite it`);
+  }
+  if (!isPlainObject(stored)) {
+    throw new Error(`stored KV record ${key} is not a JSON object; refusing to overwrite it`);
+  }
+  return JSON.stringify(mergeTenantRecord(stored, provisioned));
+}