@tokenoftrust/storefront-runner 1.3.2

package/packages/public-runtime/src/customization-preview.ts

@@ -0,0 +1,197 @@
+/**
+ * Gated preview support: signing preview access and resolving which
+ * customization environment a request sees.
+ *
+ * Two pure, runtime-portable pieces (Web Crypto + btoa/atob, no `node:*`):
+ *
+ *   1. signed, short-TTL **preview tokens** (HMAC-SHA256) that grant access to a
+ *      tenant's `test` customization on a preview host; and
+ *   2. `resolveCustomizationEnv` — the live-vs-test decision the middleware makes
+ *      per request.
+ *
+ * Security properties this enforces:
+ *   - **Production hosts never serve `test`.** A token is only consulted on a
+ *     preview host, so a leaked token can't flip a live storefront.
+ *   - **Tokens are tenant-bound.** A token minted for tenant A cannot preview
+ *     tenant B (no cross-tenant leakage).
+ *   - **Tokens expire.** `exp` is checked against the caller-supplied clock.
+ *   - **Test is never indexable.** The resolution carries `noindex: true` so the
+ *     middleware can set `X-Robots-Tag: noindex`.
+ */
+
+/** Claims carried by a preview token. */
+export interface PreviewClaims {
+  tenantId: string;
+  env: "test";
+  /** Expiry, epoch seconds. */
+  exp: number;
+}
+
+const textEncoder = new TextEncoder();
+
+function bytesToB64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64UrlToBytes(s: string): Uint8Array {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+  const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/") + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    textEncoder.encode(secret) as unknown as BufferSource,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+/**
+ * Mint a preview token: `<payloadB64Url>.<sigB64Url>`. `ttlSeconds` is added to
+ * `nowSeconds` (caller supplies the clock so this stays pure/testable).
+ */
+export async function signPreviewToken(
+  secret: string,
+  tenantId: string,
+  ttlSeconds: number,
+  nowSeconds: number,
+): Promise<string> {
+  const claims: PreviewClaims = {
+    tenantId,
+    env: "test",
+    exp: nowSeconds + ttlSeconds,
+  };
+  const payload = bytesToB64Url(textEncoder.encode(JSON.stringify(claims)));
+  const key = await hmacKey(secret);
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    textEncoder.encode(payload) as unknown as BufferSource,
+  );
+  return `${payload}.${bytesToB64Url(new Uint8Array(sig))}`;
+}
+
+export type VerifyResult =
+  | { ok: true; claims: PreviewClaims }
+  | { ok: false; reason: "malformed" | "bad-signature" | "expired" };
+
+/**
+ * Verify a preview token against `secret` and the caller's clock. Signature is
+ * checked with `crypto.subtle.verify` (constant-time) before expiry.
+ */
+export async function verifyPreviewToken(
+  secret: string,
+  token: string,
+  nowSeconds: number,
+): Promise<VerifyResult> {
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: "malformed" };
+  const payload = token.slice(0, dot);
+  const sigPart = token.slice(dot + 1);
+
+  let sig: Uint8Array;
+  try {
+    sig = b64UrlToBytes(sigPart);
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const key = await hmacKey(secret);
+  const valid = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    sig as unknown as BufferSource,
+    textEncoder.encode(payload) as unknown as BufferSource,
+  );
+  if (!valid) return { ok: false, reason: "bad-signature" };
+
+  let claims: PreviewClaims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(b64UrlToBytes(payload)));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+  if (
+    !claims ||
+    claims.env !== "test" ||
+    typeof claims.tenantId !== "string" ||
+    typeof claims.exp !== "number"
+  ) {
+    return { ok: false, reason: "malformed" };
+  }
+  if (claims.exp <= nowSeconds) return { ok: false, reason: "expired" };
+  return { ok: true, claims };
+}
+
+export type CustomizationEnv = "live" | "test";
+
+export interface EnvResolutionInput {
+  /** True when the request arrived on a preview host (e.g. `preview.*`). */
+  isPreviewHost: boolean;
+  /** The tenant resolved for this request. */
+  tenantId: string;
+  /** Token from `?__preview=` or the `tot_preview` cookie, if any. */
+  token?: string | null;
+  /** Platform preview-signing secret (env), if configured. */
+  secret?: string | null;
+  nowSeconds: number;
+}
+
+export interface EnvResolution {
+  env: CustomizationEnv;
+  /** Set `X-Robots-Tag: noindex` when true (test is never indexable). */
+  noindex: boolean;
+  /** When set, the middleware should short-circuit with this status. */
+  reject?: { status: number; message: string };
+}
+
+/**
+ * Decide which customization environment to serve. Production hosts always get
+ * `live` and never consult a token. Preview hosts are auth-gated: a valid,
+ * unexpired, tenant-matching token yields `test` (noindex); anything else is
+ * rejected.
+ */
+export async function resolveCustomizationEnv(
+  input: EnvResolutionInput,
+): Promise<EnvResolution> {
+  if (!input.isPreviewHost) {
+    return { env: "live", noindex: false };
+  }
+  if (!input.secret) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 503, message: "Preview is not configured." },
+    };
+  }
+  if (!input.token) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 401, message: "Preview token required." },
+    };
+  }
+  const result = await verifyPreviewToken(input.secret, input.token, input.nowSeconds);
+  if (!result.ok) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 401, message: `Invalid preview token (${result.reason}).` },
+    };
+  }
+  if (result.claims.tenantId !== input.tenantId) {
+    return {
+      env: "live",
+      noindex: true,
+      reject: { status: 403, message: "Preview token is for a different tenant." },
+    };
+  }
+  return { env: "test", noindex: true };
+}

package/packages/public-runtime/src/customization-reconcile.ts

@@ -0,0 +1,63 @@
+/**
+ * Types for the tenant preview model: the `.tot/config.json` mapping shape and
+ * the preview-state record — which commit a tenant's preview targets vs. what is
+ * currently rendered — plus its KV key. Read-only shapes; no logic here.
+ */
+
+/** Repo-relative path of the tenant repo's mapping config. */
+export const TOT_CONFIG_PATH = ".tot/config.json";
+
+/** One mapping from a tenant-repo prefix to a storefront artifact path. */
+export interface TotRepoMapping {
+  /** Tenant-repo path/prefix (e.g. "theme.json", "content/", "public/"). */
+  workspace: string;
+  /** Storefront artifact path/prefix it maps to. */
+  repo: string;
+  kind: "file" | "tree";
+}
+export interface TotRepoConfig {
+  tenant: string;
+  scope?: string;
+  mappings: TotRepoMapping[];
+}
+
+/** One compliance check row (mirrors @tot/private-controlplane's EvidenceCheck —
+ * kept structural here so this read-only type stays dependency-free). */
+export interface PreviewStateEvidenceCheck {
+  id: string;
+  label: string;
+  status: string;
+  detail?: string;
+  /** A concrete fix suggestion for a non-pass check (evidence producer's own —
+   * the same "why" + "fix" the CLI's `tot submit --watch` prints). */
+  hint?: string;
+  /** Whether this check is ship-blocking (REQUIRED_FOR_PROMOTE). Computed at
+   * merge time (preview-state-evidence.ts), not stored by the producer. */
+  required?: boolean;
+}
+
+/** Fail-safe preview state — target/actual can diverge when target is broken. */
+export interface PreviewState {
+  tenantId: string;
+  /** The commit the dev wants previewed. */
+  target: string | null;
+  /** The commit currently rendered (last successfully materialized). */
+  actual: string | null;
+  /** Why target != actual, when the target failed to render. Null on success. */
+  lastError: string | null;
+  lastReconcileAt: string | null;
+  /**
+   * The compliance verdict for the last successful reconcile (ADR 0010's evidence,
+   * mirrored here so the PUBLIC, unauthenticated /preview/dashboard page can show
+   * it — a shareable link should be as informative as the CLI's, without an MCP
+   * round trip). Optional/absent on a record `reconcilePreview` itself wrote
+   * (that pipeline doesn't know about evidence) — only the reconcile ROUTE's
+   * post-hoc merge sets it, after `reportPreviewEvidence` computes it. Absent and
+   * `null` both mean "no verdict yet"; callers should treat them the same.
+   */
+  evidence?: { checks: PreviewStateEvidenceCheck[]; promotable: boolean; generatedAt: string } | null;
+}
+
+export function previewStateKey(tenantId: string): string {
+  return `cust:preview-state:${tenantId}`;
+}

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

@@ -0,0 +1,157 @@
+/**
+ * Runtime read path for published customizations (store→app wiring). Resolves,
+ * for a tenant + environment, the content of a published artifact from a simple
+ * key/value store — so the `{ live, test }` pointer actually selects what the
+ * storefront serves (the live domain → `live`, a gated preview → `test`).
+ *
+ * Pure + dependency-free: the caller injects a `get(key) => Promise<string|null>`
+ * (Cloudflare KV in prod, MemoryKv in dev), keeping this module storage-agnostic
+ * and unit-testable. The app layer parses the returned string into the right
+ * shape (e.g. DeepPartial<ThemeTokens>) and falls back to the build-time artifact
+ * when nothing is published (so an un-customized tenant is unaffected).
+ */
+import {
+  channelFromEnv,
+  type ChannelName,
+  type PointerRecord,
+  type SiteVersionManifest,
+} from "./customization-versioning.js";
+import type { CustomizationEnv } from "./customization-preview.js";
+
+export type KvGet = (key: string) => Promise<string | null>;
+
+/** KV key layout for the customization store (mirrors the tenant-cache style). */
+export function customizationPointerKey(tenantId: string): string {
+  return `cust:pointer:${tenantId}`;
+}
+export function customizationArtifactKey(
+  tenantId: string,
+  versionId: string,
+): string {
+  return `cust:artifact:${tenantId}:${versionId}`;
+}
+/** KV key for one immutable site-version manifest. */
+export function siteVersionKey(tenantId: string, versionId: string): string {
+  return `cust:version:${tenantId}:${versionId}`;
+}
+/** KV key for a tenant's version-history index (list of summaries). */
+export function siteVersionIndexKey(tenantId: string): string {
+  return `cust:versions:${tenantId}`;
+}
+
+/**
+ * Canonical artifact path for a tenant's theme override.
+ *
+ * Colocated layout: a tenant IS the repo-root directory `tenants/<id>/`, so the
+ * theme lives at `tenants/<id>/theme.json`. The storefront's published-content
+ * read overlay (provider.ts) keys KV artifacts by this path.
+ */
+export function themeArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/theme.json`;
+}
+
+/**
+ * Canonical artifact path for a tenant content file (e.g. "home.json"). Colocated
+ * under `tenants/<id>/content/` — see themeArtifactPath for the contract note.
+ */
+export function contentArtifactPath(tenantId: string, relative: string): string {
+  return `tenants/${tenantId}/content/${relative}`;
+}
+
+async function readPointer(
+  get: KvGet,
+  tenantId: string,
+): Promise<PointerRecord | null> {
+  const raw = await get(customizationPointerKey(tenantId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as PointerRecord;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `versionId` a channel currently points at, or null when the tenant has no
+ * channel pointer (i.e. is still on the legacy per-path model). Reads the pointer
+ * fresh; never throws.
+ */
+export async function resolveChannelVersion(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+): Promise<string | null> {
+  const pointer = await readPointer(get, tenantId);
+  return pointer?.channels?.[channel] ?? null;
+}
+
+/** Read one immutable site-version manifest, or null. Never throws. */
+export async function readSiteVersion(
+  get: KvGet,
+  tenantId: string,
+  versionId: string,
+): Promise<SiteVersionManifest | null> {
+  const raw = await get(siteVersionKey(tenantId, versionId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as SiteVersionManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a single artifact's content via the VERSIONED path:
+ * channel → versionId → site-version manifest → content hash → bytes. Returns
+ * null (so the caller falls back to build-time) when the tenant has no channel
+ * pointer, the version manifest is missing, the path isn't in the snapshot, or
+ * the content is gone. Never throws.
+ */
+export async function readVersionedArtifact(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+  path: string,
+): Promise<string | null> {
+  const versionId = await resolveChannelVersion(get, tenantId, channel);
+  if (!versionId) return null;
+  const manifest = await readSiteVersion(get, tenantId, versionId);
+  const contentHash = manifest?.artifacts?.[path];
+  if (!contentHash) return null;
+  return get(customizationArtifactKey(tenantId, contentHash));
+}
+
+/**
+ * Read the published artifact content for (tenant, env, path), or null when
+ * nothing is published (no pointer, no selection for that path, or no stored
+ * content). Never throws on malformed data — returns null so the caller falls
+ * back to the build-time artifact.
+ *
+ * Resolution is versioned-first with a legacy fallback:
+ *   - If the tenant has a channel pointer for the resolved channel
+ *     (`channelFromEnv(env)`), resolve via the immutable site version. A channel
+ *     pointer is AUTHORITATIVE — if the snapshot omits this path we return null
+ *     (fall back to build-time), never the stale legacy selection.
+ *   - Otherwise fall back to the LEGACY per-artifact-path selection
+ *     (`pointer[env][path]`), so tenants not yet cut over are unaffected.
+ */
+export async function readPublishedArtifact(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+  path: string,
+): Promise<string | null> {
+  const pointer = await readPointer(get, tenantId);
+  if (!pointer) return null;
+
+  const channel = channelFromEnv(env);
+  if (pointer.channels?.[channel]) {
+    // Versioned model engaged for this channel — authoritative.
+    return readVersionedArtifact(get, tenantId, channel, path);
+  }
+
+  // Legacy per-path selection.
+  const versionId = pointer?.[env]?.[path];
+  if (!versionId) return null;
+  return get(customizationArtifactKey(tenantId, versionId));
+}

package/packages/public-runtime/src/customization-scripts.ts

@@ -0,0 +1,64 @@
+/**
+ * Tenant browser-script vocabulary the renderer needs: the slot / strategy /
+ * isolation constants, the CSP hash helper, and the sandboxed widget iframe
+ * attributes the renderer draws (`components/WidgetFrame.astro`).
+ *
+ * Dependency-free + Workers-portable (Web Crypto, btoa).
+ */
+
+export const SCRIPT_SLOTS = [
+  "product.aside",
+  "home.section",
+  "global.footer",
+] as const;
+export const SCRIPT_STRATEGIES = ["defer", "on-idle", "on-interaction"] as const;
+export const SCRIPT_ISOLATIONS = ["sandbox", "inline"] as const;
+
+export type ScriptSlot = (typeof SCRIPT_SLOTS)[number];
+export type ScriptStrategy = (typeof SCRIPT_STRATEGIES)[number];
+export type ScriptIsolation = (typeof SCRIPT_ISOLATIONS)[number];
+
+export interface ScriptRegistration {
+  src: string;
+  slot: ScriptSlot;
+  strategy: ScriptStrategy;
+  isolation: ScriptIsolation;
+}
+
+/** The base64 `'sha256-…'` CSP source expression that pins this exact bundle. */
+export async function cspHash(content: string | Uint8Array): Promise<string> {
+  const bytes =
+    typeof content === "string" ? new TextEncoder().encode(content) : content;
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    bytes as unknown as BufferSource,
+  );
+  let bin = "";
+  for (const b of new Uint8Array(digest)) bin += String.fromCharCode(b);
+  return `'sha256-${btoa(bin)}'`;
+}
+
+/**
+ * Sandbox token list for tenant widgets: scripts only, **no
+ * `allow-same-origin`**. Omitting same-origin forces an opaque origin, so the
+ * widget is cross-origin to the page — it cannot read parent cookies/DOM, nor
+ * its own cookies/localStorage — even when served from the platform's own
+ * origin. That's why v1 needs no separate widget domain.
+ */
+export const WIDGET_SANDBOX = "allow-scripts";
+
+export interface WidgetFrameAttrs {
+  sandbox: string;
+  loading: "eager" | "lazy";
+  referrerpolicy: "no-referrer";
+}
+
+/** Iframe attributes for a sandboxed widget, derived from its load strategy. */
+export function widgetFrameAttrs(strategy: ScriptStrategy): WidgetFrameAttrs {
+  return {
+    sandbox: WIDGET_SANDBOX,
+    // "defer" loads with the page; idle/interaction defer to lazy (near-viewport).
+    loading: strategy === "defer" ? "eager" : "lazy",
+    referrerpolicy: "no-referrer",
+  };
+}

package/packages/public-runtime/src/customization-versioning.ts

@@ -0,0 +1,95 @@
+/**
+ * Pointer/selection **types** for published customizations, as the storefront
+ * read path sees them: which content version is selected for `live` vs `test`,
+ * per artifact path. Types only — nothing here reads, writes, or mutates state.
+ */
+
+/** Metadata for one immutable, content-addressed artifact version. */
+export interface ArtifactVersion {
+  tenantId: string;
+  /** Repo-relative tenant-owned path (e.g. themes/tenants/<id>.theme.json). */
+  path: string;
+  /** Content-addressed id: sha256(content) hex. */
+  versionId: string;
+  size: number;
+  createdAt: string;
+}
+
+/** Which version of each artifact is selected for an environment. */
+export type Selection = Record<string, string>;
+
+/**
+ * A publish **channel**: the audience-facing surface a request resolves to.
+ * `live` is what production hosts serve; `preview` is what a gated preview host
+ * serves. (The middleware's `CustomizationEnv` "test" maps to the `preview`
+ * channel — see `channelFromEnv`.)
+ */
+export type ChannelName = "live" | "preview";
+
+/** Channel → versionId. Optional/partial: a channel may be unset. */
+export type ChannelPointers = Partial<Record<ChannelName, string>>;
+
+/**
+ * Per-tenant pointer record.
+ *
+ * - `live` / `test`: the LEGACY per-artifact-path selections (kept so tenants not
+ *   yet cut over to the versioned model resolve exactly as before).
+ * - `channels`: the versioned-publish channel pointers (`live`/`preview` →
+ *   a single site `versionId`). Additive + optional; when present it is
+ *   authoritative for that channel and shadows the legacy selection.
+ * - `rev`: optimistic-concurrency token, incremented on every successful write.
+ */
+export interface PointerRecord {
+  tenantId: string;
+  rev: number;
+  live: Selection;
+  test: Selection;
+  channels?: ChannelPointers;
+}
+
+export function emptyPointer(tenantId: string): PointerRecord {
+  return { tenantId, rev: 0, live: {}, test: {} };
+}
+
+/**
+ * Map the middleware's customization env to a publish channel. Production hosts
+ * resolve `live` → `live`; a gated preview resolves `test` → `preview`.
+ */
+export function channelFromEnv(env: "live" | "test"): ChannelName {
+  return env === "live" ? "live" : "preview";
+}
+
+/**
+ * A reference to a tenant's public-asset bundle for a version. The asset lane
+ * stores the BYTES in R2 keyed by this same `versionId`; the site-version
+ * manifest carries only the reference (publish never writes asset bytes).
+ */
+export interface AssetBundleRef {
+  versionId: string;
+  count?: number;
+}
+
+/**
+ * An immutable, content-addressed snapshot of a tenant's whole site, keyed by a
+ * single `versionId` (a Gitea commit sha, or a content hash when there is no
+ * commit). `artifacts` maps each artifact path to the sha256 of its content; the
+ * bytes live at `cust:artifact:<tenant>:<contentHash>` (the existing, deduped
+ * content store). `assets` references the public-asset bundle (bytes owned by the
+ * asset lane's R2). A version is written once and never mutated.
+ */
+export interface SiteVersionManifest {
+  tenantId: string;
+  versionId: string;
+  source: "commit" | "hash";
+  createdAt: string;
+  artifacts: Record<string, string>;
+  assets?: AssetBundleRef;
+}
+
+/** Compact list-index entry for version history (KV has no cheap scan). */
+export interface SiteVersionSummary {
+  versionId: string;
+  source: "commit" | "hash";
+  createdAt: string;
+  artifactCount: number;
+}