@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/lib/dev/cliSignInCode.ts

@@ -0,0 +1,155 @@
+/**
+ * Mint a browserless "get going" command for an ALREADY-AUTHENTICATED developer — the
+ * second half of the invite story. The developer accepted the magic link (OTP-free web
+ * sign-in) and landed on /dev; this hands them a single-copy, TWO-LINE paste — line 1 signs
+ * the terminal in with the one-time code, line 2 runs `start` (checkout → run → open the
+ * browser on the working site) — so they go from web sign-in to a running store with NO
+ * second browser round-trip and NO OTP.
+ *
+ * The token is minted by the MCP (POST /api/internal/dev-access/cli-signin-code), bound
+ * to the MCP's OWN audience, so it's redeemable only by that same MCP's /oauth/redeem-code
+ * — exactly what `tot login --code` does. We reuse the SAME seam as the app-binding writer:
+ *   - MCP host  ← the ORIGIN of MCP_APP_BINDING_URL (one source, so the mint host and the
+ *                 --mcp host the developer runs are provably the same MCP tier).
+ *   - auth      ← header x-mcp-service-secret: MCP_SERVICE_SHARED_SECRET (the storefront
+ *                 never holds the MCP's core credential).
+ *
+ * Line 1 appends `--mcp <origin>` ONLY when the MCP is not the CLI's built-in prod default —
+ * on prod the shortest form (`npx @tokenoftrust/cli login --code <token>`) is emitted.
+ *
+ * `activityBridge` (optional) piggybacks the local→hosted activity-bridge credential
+ * (see lib/dev/activityIngestToken.ts) onto the SAME pasted line as two extra `tot
+ * login` flags — no second browser round-trip, no MCP-repo change. `tot login`
+ * caches it in ~/.tot/credentials.json, and `tot dev` threads it into the spawned
+ * dev-loop process so it can report file saves to the developer's own hosted /dev
+ * panel. Omitted entirely when the caller has no SESSION KV to mint against — the
+ * local loop then simply runs with no hosted signal, same as today.
+ */
+import { readEnv } from "@/lib/env";
+
+// The CLI's built-in default MCP (packages/cli login.mjs DEFAULT_MCP_URL). When the derived
+// MCP origin equals this, --mcp is redundant noise, so we omit it.
+const PROD_MCP_ORIGIN = "https://mcp.tokenoftrust.com";
+
+export interface HttpTransport {
+  post(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+}
+
+export type CliSignInCodeResult =
+  | { ok: true; command: string; expiresAt: string | null }
+  | { ok: false; status: 502 | 503; reason: string };
+
+/**
+ * Mint the ready-to-paste CLI sign-in command for `email`. The caller MUST pass the
+ * VERIFIED session email (never a client-supplied value) — a signed-in developer can only
+ * mint a code for themselves. `tenant` (the developer's own vendor, session-derived) is
+ * threaded to the MCP so the code is TENANT-SCOPED: the redeemed CLI session lands
+ * already bound to that store (no client_list round-trip; see the route header). Older
+ * MCP deploys ignore the extra field — additive, never breaking. Fail-closed: an
+ * unconfigured seam (no URL/secret) or a 401 (MCP route unmounted / bad secret) is a 503;
+ * any other non-2xx / transport / parse fault is a 502. Never throws.
+ */
+export async function mintCliSignInCommand(
+  email: string,
+  tenant: string | null = null,
+  deps: { transport?: HttpTransport } = {},
+  activityBridge: { token: string; url: string } | null = null,
+): Promise<CliSignInCodeResult> {
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!bindingUrl || !secret) {
+    return { ok: false, status: 503, reason: "not-configured" };
+  }
+  let mcpOrigin: string;
+  let endpoint: string;
+  try {
+    mcpOrigin = new URL(bindingUrl).origin;
+    // Mounted OUTSIDE /api on the MCP (the /api surface there is session-guarded); use the
+    // origin of MCP_APP_BINDING_URL, not its full path.
+    endpoint = `${mcpOrigin}/internal/dev-access/cli-signin-code`;
+  } catch {
+    return { ok: false, status: 503, reason: "bad-mcp-url" };
+  }
+
+  const transport = deps.transport ?? new FetchHttpTransport();
+  let res: { status: number; json(): Promise<unknown> };
+  try {
+    res = await transport.post(
+      endpoint,
+      { "x-mcp-service-secret": secret },
+      {
+        email: email.toLowerCase(),
+        ...(tenant ? { tenant: tenant.toLowerCase() } : {}),
+      },
+    );
+  } catch (cause) {
+    return {
+      ok: false,
+      status: 502,
+      reason: "mcp request failed: " + (cause instanceof Error ? cause.message : String(cause)),
+    };
+  }
+
+  if (res.status < 200 || res.status >= 300) {
+    // 401 = MCP route unmounted or bad shared secret → treat as not-configured (503).
+    return {
+      ok: false,
+      status: res.status === 401 ? 503 : 502,
+      reason: `mcp cli-signin-code returned status ${res.status}`,
+    };
+  }
+
+  let payload: { token?: string; expiresAt?: string };
+  try {
+    payload = (await res.json()) as typeof payload;
+  } catch {
+    return { ok: false, status: 502, reason: "unparseable mcp response" };
+  }
+  if (!payload.token) {
+    return { ok: false, status: 502, reason: "mcp returned no token" };
+  }
+
+  const mcpFlag = mcpOrigin === PROD_MCP_ORIGIN ? "" : ` --mcp ${mcpOrigin}`;
+  // Piggyback the activity-bridge credential onto the SAME login line — additive
+  // flags, ignored by older CLI builds that don't yet recognize them.
+  const activityFlags = activityBridge
+    ? ` --activity-token ${activityBridge.token} --activity-url ${activityBridge.url}`
+    : "";
+  // A single copy → a three-line paste that takes the developer all the way to a running
+  // store, no browser, AND leaves `tot` on their PATH so every later command is a bare
+  // `tot …` (not `npx @tokenoftrust/cli …`):
+  //   1. `npm i -g @tokenoftrust/cli` — install the `tot` command once.
+  //   2. `tot login --code <token>` — sign the terminal in with the single-use code.
+  //   3. `tot start` — checkout + run + open the browser on the working site, reusing the
+  //      session step 2 just cached (so `start` never opens its own sign-in).
+  //
+  // The trailing `&&` chains them: each step runs ONLY if the previous succeeded. In
+  // particular a stale/burned code (single-use, short-TTL) fails step 2 and stops there
+  // with `login`'s clear "ask for a fresh invite" error — it never falls through to
+  // `start`'s BROWSER sign-in (the surprise we're avoiding).
+  const command = [
+    `npm i -g @tokenoftrust/cli &&`,
+    `tot login --code ${payload.token}${mcpFlag}${activityFlags} &&`,
+    `tot start`,
+  ].join("\n");
+  return {
+    ok: true,
+    command,
+    expiresAt: payload.expiresAt ?? null,
+  };
+}

package/apps/storefront/src/lib/dev/devDraft.ts

@@ -0,0 +1,133 @@
+/**
+ * Per-developer DRAFT overlay for the /dev live preview — the signed token + KV key
+ * contract behind decision `draft-overlay-same-origin` (workstream 8500-dev-live-preview).
+ *
+ * WHAT A DRAFT IS: when the /dev page's onscreen AI loop edits the developer's site
+ * (`/api/content-edit/ai-edit`), the edited artifacts land in TENANT_CACHE KV under
+ * `dev-draft:<tenantId>:<draftId>:<path>` and the developer gets a signed, tenant-bound,
+ * short-TTL `tot_dev_draft` cookie. The middleware overlays those artifacts onto content
+ * + theme ONLY for requests carrying a verifying cookie for the resolved tenant — so the
+ * editing developer sees (and can interact with) their change in the same-origin live
+ * preview instantly, while live/test channels and every other viewer are untouched.
+ * Compliance gating stays at publish/submit (gate-at-publish), not at edit.
+ *
+ * TRUST MODEL: identical to the existing preview token (customization-preview.ts) —
+ * HMAC-SHA256 over the claims payload with CUSTOMIZATION_PREVIEW_SECRET, expiry checked
+ * against a caller-supplied clock, tenant-bound so a token for tenant A can never
+ * surface tenant B's draft. Pure Web Crypto; renderer/Workers-safe; never throws.
+ */
+
+/** Cookie carrying the signed draft token. HttpOnly; never readable by page script. */
+export const DEV_DRAFT_COOKIE = "tot_dev_draft";
+
+/** Draft artifacts live this long (KV TTL + token TTL + cookie max-age), seconds. */
+export const DEV_DRAFT_TTL_SECONDS = 7 * 24 * 3600;
+
+/** Claims carried by a draft token. */
+export interface DevDraftClaims {
+  tenantId: string;
+  /** Opaque per-draft id (random UUID) — partitions one developer's draft from another's. */
+  draftId: string;
+  /** Expiry, epoch seconds. */
+  exp: number;
+}
+
+/**
+ * KV key for one draft artifact. `path` mirrors the tenant repo layout the rest of the
+ * customization store uses: "content/home.html", "content/pages-html/<slug>.html",
+ * "theme.json".
+ */
+export function devDraftKey(tenantId: string, draftId: string, path: string): string {
+  return `dev-draft:${tenantId}:${draftId}:${path}`;
+}
+
+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 draft token: `<payloadB64Url>.<sigB64Url>` (same wire shape as preview tokens). */
+export async function signDevDraftToken(
+  secret: string,
+  tenantId: string,
+  draftId: string,
+  ttlSeconds: number,
+  nowSeconds: number,
+): Promise<string> {
+  const claims: DevDraftClaims = { tenantId, draftId, 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))}`;
+}
+
+/**
+ * Verify a draft token; returns the claims or null (bad shape, bad signature, expired,
+ * malformed claims). Constant-time signature check before anything else is trusted.
+ */
+export async function verifyDevDraftToken(
+  secret: string,
+  token: string,
+  nowSeconds: number,
+): Promise<DevDraftClaims | null> {
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) return null;
+  const payload = token.slice(0, dot);
+
+  let sig: Uint8Array;
+  try {
+    sig = b64UrlToBytes(token.slice(dot + 1));
+  } catch {
+    return null;
+  }
+  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 null;
+
+  let claims: DevDraftClaims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(b64UrlToBytes(payload)));
+  } catch {
+    return null;
+  }
+  if (
+    !claims ||
+    typeof claims.tenantId !== "string" ||
+    typeof claims.draftId !== "string" ||
+    typeof claims.exp !== "number" ||
+    claims.exp <= nowSeconds
+  ) {
+    return null;
+  }
+  return claims;
+}

package/apps/storefront/src/lib/dev/hostedCockpit.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared auth + tenant + provider resolution for the hosted /dev cockpit's
+ * /api/dev/* routes (cp-tree, cp-file, cp-write, and cp-diff/cp-locate landing
+ * on top). Mirrors /api/content-edit/ai-edit's gate exactly: a signed-in
+ * developer session with a real capability, resolving only the session's OWN
+ * tenant — never a caller-supplied one. See decision
+ * architecture-environment-aware-cockpit (workstream tot-lime-cloud-dev-cockpit).
+ *
+ * Also carries the path resolution + draft-overlay helpers shared by
+ * cp-file/cp-write/cp-diff, so the three routes agree on exactly one
+ * definition of "the writable surface" and "the developer's current value for
+ * a path" (draft-if-present else published) rather than three copies drifting.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { json } from "@/lib/grants/route.js";
+import { readEnv, readKv } from "@/lib/env";
+import { resolvePreviewTenant } from "@/config/previewTenantLookup";
+import { createContentProvider, type ContentProvider } from "@/lib/storyblok/provider";
+import { readPublishedArtifact, themeArtifactPath } from "@tot/public-runtime";
+import type { TenantConfig } from "@tot/public-runtime";
+import {
+  DEV_DRAFT_COOKIE,
+  DEV_DRAFT_TTL_SECONDS,
+  devDraftKey,
+  signDevDraftToken,
+  verifyDevDraftToken,
+} from "@/lib/dev/devDraft";
+
+export interface CockpitContext {
+  tenant: TenantConfig;
+  provider: ContentProvider;
+  kvGet: (key: string) => Promise<string | null>;
+  kvPut: ((key: string, value: string, opts: { expirationTtl: number }) => Promise<void>) | null;
+  draftSecret: string | null;
+}
+
+/** Resolved context, or a Response the caller should return as-is (401/403). */
+export async function resolveCockpitContext(
+  context: APIContext,
+): Promise<CockpitContext | Response> {
+  const session = await readViewerSession({ cookies: context.cookies });
+  if (!session) return json({ ok: false, message: "sign in required" }, 401);
+  if (!session.capability || session.capability === "none") {
+    return json({ ok: false, message: "no developer capability on this account" }, 403);
+  }
+
+  // The tenant is the session's OWN store (first membership, else the session's
+  // primary resource) — the same resolution /dev renders with and ai-edit.ts
+  // authenticates edits against. No caller-supplied tenant is ever honored.
+  const wanted = (session.tenants?.[0]?.resource ?? session.resource ?? "").toLowerCase();
+  const tenant = wanted ? await resolvePreviewTenant(wanted) : null;
+  if (!tenant) return json({ ok: false, message: "no store linked to this account" }, 403);
+
+  const kv = await readKv("TENANT_CACHE");
+  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+  const kvPut = kv
+    ? (key: string, value: string, opts: { expirationTtl: number }) => kv.put(key, value, opts)
+    : null;
+  const draftSecret = (await readEnv("CUSTOMIZATION_PREVIEW_SECRET")) ?? null;
+  const provider = createContentProvider(tenant, kv ? { get: kvGet, env: "live" } : undefined);
+
+  return { tenant, provider, kvGet, kvPut, draftSecret };
+}
+
+export function isCockpitContext(v: CockpitContext | Response): v is CockpitContext {
+  return !(v instanceof Response);
+}
+
+// ---------------------------------------------------------------------------
+// The writable surface: content/home.html, content/pages-html/<slug>.html,
+// theme.json — exactly scripts/dev/safe-path.mjs's WRITE_ALLOWLIST, mirrored
+// here since the hosted Worker has no filesystem to check it against.
+// ---------------------------------------------------------------------------
+
+const PAGE_HTML_RE = /^content\/pages-html\/([^\0]+)\.html$/;
+
+export function pageSlugForPath(path: string): string | null {
+  return PAGE_HTML_RE.exec(path)?.[1] ?? null;
+}
+
+export function isWritablePath(path: string): boolean {
+  return path === "content/home.html" || path === "theme.json" || PAGE_HTML_RE.test(path);
+}
+
+export function languageForPath(path: string): string | null {
+  if (path === "theme.json") return "json";
+  if (path === "content/home.html" || PAGE_HTML_RE.test(path)) return "html";
+  return null;
+}
+
+/** The PUBLISHED value for one of the three writable-surface paths, or null if unknown/absent. */
+export async function readPublishedPath(ctx: CockpitContext, path: string): Promise<string | null> {
+  if (path === "content/home.html") return ctx.provider.getHomeHtml();
+  if (path === "theme.json") {
+    return readPublishedArtifact(ctx.kvGet, ctx.tenant.tenant_id, "live", themeArtifactPath(ctx.tenant.tenant_id));
+  }
+  const slug = pageSlugForPath(path);
+  if (slug) return ctx.provider.getPageHtml(slug);
+  return null;
+}
+
+/**
+ * Deterministic small hash, standing in for the local file-writer's mtimeMs as
+ * an opaque "version" the client round-trips as `baseVersion` (C6 stale-write
+ * guard) — there's no filesystem here to stat. null in, null out (mirrors the
+ * local contract's `current: null` for "doesn't exist yet").
+ */
+export function contentVersion(content: string | null): number | null {
+  if (content === null) return null;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < content.length; i++) {
+    h ^= content.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+export interface DraftState {
+  /** The developer's existing draft id if their cookie verifies for this tenant, else a fresh one. */
+  draftId: string;
+  /** Draft-overlay value for `path` if one exists, else null. */
+  draftContent: string | null;
+}
+
+/** Resolve (or mint) this request's draft id + this path's current draft-overlay value, if any. */
+export async function resolveDraftState(
+  context: APIContext,
+  ctx: CockpitContext,
+  path: string,
+): Promise<DraftState> {
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const priorCookie = context.cookies.get(DEV_DRAFT_COOKIE)?.value ?? null;
+  const priorClaims =
+    priorCookie && ctx.draftSecret ? await verifyDevDraftToken(ctx.draftSecret, priorCookie, nowSeconds) : null;
+  const draftId =
+    priorClaims?.tenantId === ctx.tenant.tenant_id ? priorClaims.draftId : crypto.randomUUID();
+  const draftContent = await ctx.kvGet(devDraftKey(ctx.tenant.tenant_id, draftId, path));
+  return { draftId, draftContent };
+}
+
+/** The value the developer currently sees for `path`: their draft if present, else published. */
+export async function readEffectivePath(
+  context: APIContext,
+  ctx: CockpitContext,
+  path: string,
+): Promise<{ content: string | null; draftId: string }> {
+  const { draftId, draftContent } = await resolveDraftState(context, ctx, path);
+  if (draftContent !== null) return { content: draftContent, draftId };
+  return { content: await readPublishedPath(ctx, path), draftId };
+}
+
+/** (Re)issue the signed draft cookie so the middleware overlay + this route's own reads see it. */
+export async function setDraftCookie(
+  context: APIContext,
+  ctx: CockpitContext,
+  draftId: string,
+): Promise<void> {
+  if (!ctx.draftSecret) return;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const token = await signDevDraftToken(ctx.draftSecret, ctx.tenant.tenant_id, draftId, DEV_DRAFT_TTL_SECONDS, nowSeconds);
+  context.cookies.set(DEV_DRAFT_COOKIE, token, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax",
+    path: "/",
+    maxAge: DEV_DRAFT_TTL_SECONDS,
+  });
+}

package/apps/storefront/src/lib/dev/livePreview.ts

@@ -0,0 +1,77 @@
+/**
+ * Derive the /dev "live tenant preview" plan — whether the page embeds a real, scaled-down
+ * iframe of the developer's own storefront (click-to-zoom into a fully interactive view),
+ * and the exact same-origin src to frame. Pure and renderer-safe: reads only public tenant
+ * shape + the request host + a config flag, never a secret.
+ *
+ * WHY AN IFRAME WORKS (no screenshots, no new infra): tenant routing is host-first with a
+ * `/<appDomain>/…` path-prefix fallback on the same worker (src/lib/tenantRouting.ts), so
+ * the tenant's real site is reachable at a RELATIVE path from /dev. CSP already permits
+ * same-origin framing both directions (`frame-ancestors 'self'` + `frame-src 'self'`,
+ * packages/public-runtime/src/csp.ts) alongside `X-Frame-Options: SAMEORIGIN` — no header
+ * changes. The iframe carries the viewer's own cookies, so a signed-in developer framing
+ * their own store passes the login gate by construction; /dev only renders the iframe for
+ * that viewer (the gated/signed-out states keep the static mock).
+ *
+ * CROSS-ORIGIN GOTCHA: never frame `hostedStoreUrl` (`*.tokenoftrust.store` subdomains) —
+ * those are cross-origin from the /dev host and blocked by `frame-src 'self'`. The src here
+ * is always relative: `/` when the request host itself owns the tenant (host-first routing
+ * skips the path prefix there), else `/${appDomain}/`.
+ *
+ * CONFIG TOGGLE: `DEV_LIVE_PREVIEW` (read via the readEnv seam in dev.astro). UNSET ⇒ ON.
+ * Set to "off" / "0" / "false" to fall back to the static mock per environment without a
+ * code change — the just-in-case lever if framing misbehaves somewhere.
+ */
+import type { TenantConfig } from "@tot/public-runtime";
+
+/** Natural (unscaled) viewport the preview iframe renders at — a standard desktop. */
+export const PREVIEW_VIEWPORT = { width: 1280, height: 800 } as const;
+
+/** Fallback thumbnail scale before script measures the real container width. */
+export const PREVIEW_FALLBACK_SCALE = 0.3;
+
+export interface LivePreviewPlan {
+  /** Relative, same-origin iframe src for the tenant's real site (never a full URL). */
+  src: string;
+  width: number;
+  height: number;
+  /** Initial mini-state scale; the page script refines it to fit the container. */
+  scale: number;
+}
+
+/** `DEV_LIVE_PREVIEW` semantics: default ON; only an explicit off flips it. */
+export function livePreviewEnabled(envValue: string | undefined | null): boolean {
+  const v = (envValue ?? "").trim().toLowerCase();
+  return v !== "off" && v !== "0" && v !== "false";
+}
+
+/**
+ * The same-origin src for `tenant` as seen from `requestHost` (port ignored): `/` when the
+ * host itself owns the tenant (host-first routing serves it at the root there), else the
+ * path-prefix form `/${appDomain}/`.
+ */
+export function livePreviewSrc(tenant: TenantConfig | null, requestHost: string): string | null {
+  if (!tenant?.appDomain) return null;
+  const host = requestHost.split(":")[0]?.trim().toLowerCase() ?? "";
+  const owned = [tenant.appDomain, tenant.canonicalDomain, ...(tenant.domains ?? [])].some(
+    (d) => d?.toLowerCase() === host,
+  );
+  return owned ? "/" : `/${tenant.appDomain}/`;
+}
+
+/**
+ * The full plan, or null when the preview shouldn't render (flag off, no tenant, or the
+ * viewer isn't an admitted developer — those states keep the static mock).
+ */
+export function deriveLivePreview(opts: {
+  envValue: string | undefined | null;
+  tenant: TenantConfig | null;
+  requestHost: string;
+  /** The viewer is signed in with a developer capability (dev.astro's hasStoreAccess gate). */
+  admitted: boolean;
+}): LivePreviewPlan | null {
+  if (!opts.admitted || !livePreviewEnabled(opts.envValue)) return null;
+  const src = livePreviewSrc(opts.tenant, opts.requestHost);
+  if (!src) return null;
+  return { src, ...PREVIEW_VIEWPORT, scale: PREVIEW_FALLBACK_SCALE };
+}

package/apps/storefront/src/lib/dev/runtimeStore.ts

@@ -0,0 +1,120 @@
+/**
+ * Per-vendor "local dev runtime" latest-state — the LIVE half of the
+ * local→hosted activity bridge (G1). Where activityStore.ts holds a ring buffer
+ * of file-SAVE events, this holds ONE record per vendor: the most recent
+ * heartbeat the developer's LOCAL `tot dev`/`tot start` sent (see the CLI's
+ * dev-heartbeat.mjs). The hosted cockpit reads it to show a LIVE, clickable
+ * local-dev link + the running CLI version.
+ *
+ * Deliberately SEPARATE from the file-activity buffer: a heartbeat is
+ * latest-wins state, not an appended event, so it lives under its own
+ * `dev-runtime:<tenant>` key and never touches the ring buffer. No file CONTENT
+ * is ever stored — `url` is only the local `http://localhost:<port>/<tenant>/`
+ * (low-sensitivity, per decision).
+ *
+ * Liveness is computed SERVER-side from `aliveAt` (the ingest-time server clock,
+ * NOT the client's `at`) so a skewed local clock can't make a dead loop look
+ * live or vice-versa. Same KV binding as the activity buffer (TENANT_CACHE).
+ */
+
+/** The latest local-dev runtime state reported by a vendor's heartbeat. */
+export interface DevRuntime {
+  /** The `tot` CLI version driving the local loop, when the heartbeat carried it. */
+  cliVersion?: string;
+  /** The @tokenoftrust/storefront-runner version, when resolvable at heartbeat time. */
+  runnerVersion?: string;
+  /** The local store URL — `http://localhost:<port>/<tenant>/`. Clickable in the cockpit. */
+  url?: string;
+  /** Epoch ms of the latest heartbeat, stamped by the SERVER at ingest (skew-proof). */
+  aliveAt: number;
+}
+
+/** The runtime as the GET feed exposes it — the stored record plus a computed `live` flag. */
+export interface DevRuntimeView extends DevRuntime {
+  /** True when the last heartbeat landed within LIVE_WINDOW_MS of `now`. */
+  live: boolean;
+}
+
+const KEY_PREFIX = "dev-runtime:";
+/**
+ * How recent the last heartbeat must be to read as "live". The CLI beats every
+ * ~10s, so 30s tolerates a couple of missed/slow beats before we call the loop
+ * stale rather than flapping the badge on one dropped POST.
+ */
+export const LIVE_WINDOW_MS = 30_000;
+/**
+ * Keep a stopped loop's LAST runtime around a while so the cockpit can still
+ * show "last seen … / CLI vX.Y" (with live:false) after the developer quits —
+ * but not forever. Refreshed on every heartbeat, so an active loop never lapses.
+ */
+const TTL_SECONDS = 3600;
+
+/** Cap the free-text fields a bridge-token holder can push into KV. */
+const MAX_VERSION_LEN = 64;
+const MAX_URL_LEN = 256;
+
+function key(appDomain: string): string {
+  return KEY_PREFIX + appDomain;
+}
+
+function clip(v: unknown, max: number): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v.slice(0, max) : undefined;
+}
+
+/**
+ * Accept ONLY a local http URL for the clickable cockpit link. The cockpit
+ * renders this as an `<a href>`, so a bounded string isn't enough — a
+ * non-localhost host or a non-http scheme (a phishing URL, `javascript:` …)
+ * must never be stored/rendered. Self-targeted today (the ingest token is the
+ * developer's own), but validating at the store closes the vector at the source.
+ */
+function localUrl(v: unknown): string | undefined {
+  const s = clip(v, MAX_URL_LEN);
+  return s && /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/i.test(s) ? s : undefined;
+}
+
+/**
+ * Normalize a raw heartbeat body into a stored DevRuntime — dropping anything
+ * that isn't a bounded string and stamping the SERVER's `aliveAt`. Pure +
+ * exported so the route's shaping is unit-tested without KV.
+ */
+export function shapeRuntime(
+  body: { cliVersion?: unknown; runnerVersion?: unknown; url?: unknown },
+  aliveAt: number,
+): DevRuntime {
+  const rt: DevRuntime = { aliveAt };
+  const cliVersion = clip(body.cliVersion, MAX_VERSION_LEN);
+  const runnerVersion = clip(body.runnerVersion, MAX_VERSION_LEN);
+  const url = localUrl(body.url);
+  if (cliVersion) rt.cliVersion = cliVersion;
+  if (runnerVersion) rt.runnerVersion = runnerVersion;
+  if (url) rt.url = url;
+  return rt;
+}
+
+/** Read the vendor's latest runtime, or null when none/malformed. Never throws. */
+export async function readRuntime(kv: KVNamespace, appDomain: string): Promise<DevRuntime | null> {
+  try {
+    const raw = await kv.get(key(appDomain));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.aliveAt !== "number") return null;
+    return parsed as DevRuntime;
+  } catch {
+    return null;
+  }
+}
+
+/** Overwrite the vendor's runtime with the latest heartbeat (latest-wins, TTL'd). */
+export async function writeRuntime(
+  kv: KVNamespace,
+  appDomain: string,
+  rt: DevRuntime,
+): Promise<void> {
+  await kv.put(key(appDomain), JSON.stringify(rt), { expirationTtl: TTL_SECONDS });
+}
+
+/** Attach the computed `live` flag (aliveAt within LIVE_WINDOW_MS of `now`). Pure. */
+export function toRuntimeView(rt: DevRuntime, now: number = Date.now()): DevRuntimeView {
+  return { ...rt, live: now - rt.aliveAt <= LIVE_WINDOW_MS };
+}