@tokenoftrust/storefront-runner 0.1.0

package/apps/storefront/src/lib/demoGate.ts

@@ -0,0 +1,113 @@
+/**
+ * Demo password gate (HTTP Basic Auth) for named hosts.
+ *
+ * A lightweight "put a password in front of it before we show it" gate for demo
+ * subdomains (e.g. bigdvapor.tokenoftrust.store). Deliberately DISTINCT from the
+ * ShipLoop customization-preview gate (resolveCustomizationEnv / `preview.` hosts
+ * + signed, tenant-bound tokens): this is a single shared static password,
+ * browser-native, covering every path + subresource on the host. It runs first
+ * in the middleware so a blocked host never reaches tenant resolution, the edge
+ * cache, or any render.
+ *
+ * Config is env-driven so gating/ungating a host or rotating the password needs
+ * NO code change:
+ *   DEMO_GATE_HOSTS    comma-separated hostnames to gate ("" / unset = none)
+ *   DEMO_GATE_PASSWORD the shared password (set via `wrangler secret`; unset = off)
+ *   DEMO_GATE_REALM    optional Basic-Auth realm label (default "Demo")
+ *
+ * The username is IGNORED — share it as "any username, password: …", the usual
+ * demo pattern. If no password is configured the gate is a no-op everywhere.
+ */
+
+const REALM_FALLBACK = "Demo";
+
+/** Lowercase, trim, and drop any `:port` suffix so host matching is exact. */
+export function normalizeHost(host: string): string {
+  return host.trim().toLowerCase().replace(/:\d+$/, "");
+}
+
+/**
+ * True when `host` matches the comma-separated gate list (case/port-insensitive).
+ *
+ * Entries are either an exact host (`storefront.tokenoftrust.workers.dev`) or a
+ * leading-`*.` wildcard (`*.tokenoftrust.store`) that matches ANY subdomain of
+ * that zone at any depth — `bigdvapor.tokenoftrust.store`,
+ * `storefront.tokenoftrust.store`, `preview.acme.tokenoftrust.store` — but NOT
+ * the bare apex. Wildcards are what let us gate every tenant (present + future)
+ * on a shared zone without enumerating each host.
+ */
+export function hostInGateList(host: string, hostsCsv: string | null | undefined): boolean {
+  const h = normalizeHost(host);
+  const list = (hostsCsv ?? "").split(",").map(normalizeHost).filter(Boolean);
+  for (const entry of list) {
+    if (entry.startsWith("*.")) {
+      const suffix = entry.slice(1); // ".tokenoftrust.store"
+      if (h.length > suffix.length && h.endsWith(suffix)) return true;
+    } else if (h === entry) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Parse the password out of an `Authorization: Basic …` header; null if absent/malformed. */
+function passwordFromAuthHeader(header: string | null): string | null {
+  if (!header) return null;
+  const [scheme, encoded] = header.split(" ");
+  if (!scheme || scheme.toLowerCase() !== "basic" || !encoded) return null;
+  let decoded: string;
+  try {
+    decoded = atob(encoded);
+  } catch {
+    return null;
+  }
+  const colon = decoded.indexOf(":");
+  if (colon === -1) return null;
+  return decoded.slice(colon + 1);
+}
+
+/** Length-hiding constant-time-ish string equality (avoids early-exit timing leaks). */
+function safeEqual(a: string, b: string): boolean {
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  }
+  return diff === 0;
+}
+
+export interface DemoGateEnv {
+  hosts?: string | null;
+  password?: string | null;
+  realm?: string | null;
+}
+
+/**
+ * Decide whether a request to `host` is allowed past the demo gate.
+ * Returns a 401 Response to send when the gate blocks; null when the host is
+ * ungated, the gate is disabled, or valid credentials were supplied.
+ */
+export function evaluateDemoGate(
+  host: string,
+  authorization: string | null,
+  env: DemoGateEnv,
+): Response | null {
+  const password = env.password?.trim();
+  if (!password) return null; // no password configured → gate disabled globally
+
+  if (!hostInGateList(host, env.hosts)) return null; // this host isn't gated
+
+  const supplied = passwordFromAuthHeader(authorization);
+  if (supplied !== null && safeEqual(supplied, password)) return null; // authorized
+
+  const realm = (env.realm?.trim() || REALM_FALLBACK).replace(/"/g, "");
+  return new Response("Authentication required.", {
+    status: 401,
+    headers: {
+      "WWW-Authenticate": `Basic realm="${realm}", charset="UTF-8"`,
+      "Content-Type": "text/plain; charset=utf-8",
+      // Never let a browser/CDN cache the challenge or a would-be authorized body.
+      "Cache-Control": "no-store",
+    },
+  });
+}

package/apps/storefront/src/lib/dev/ai-widget-client.js

@@ -0,0 +1,127 @@
+// The floating "✦ ask" affordance for `tot dev`'s inline-AI edit loop (WS5 G1).
+// Injected into every page ONLY in `astro dev` by inlineAiEditPlugin in
+// astro.config.mjs (never bundled into the production build — this file isn't
+// imported by any Astro page/component, only served verbatim by that dev-only
+// Vite middleware). Talks to /__tot/ai-edit and /__tot/ai-undo, which
+// scripts/dev/ai-edit.mjs implements against the tenant this `tot dev` run is
+// serving (TOT_DEV_TENANT).
+//
+// Plain vanilla JS, no build step, no framework — this never ships to users.
+
+(function () {
+  const ROOT_ID = "__tot-ai-widget";
+  if (document.getElementById(ROOT_ID)) return; // one instance per page
+
+  const root = document.createElement("div");
+  root.id = ROOT_ID;
+  root.innerHTML = `
+    <style>
+      #${ROOT_ID} { position: fixed; right: 1rem; bottom: 1rem; z-index: 2147483647;
+        font: 14px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      #${ROOT_ID} .toggle { width: 3rem; height: 3rem; border-radius: 999px; border: none;
+        background: #16181d; color: #e8e6e0; font-size: 1.25rem; cursor: pointer;
+        box-shadow: 0 8px 24px -8px rgba(0,0,0,.45); }
+      #${ROOT_ID} .toggle:hover { background: #23262d; }
+      #${ROOT_ID} .panel { display: none; position: absolute; right: 0; bottom: 3.75rem;
+        width: 22rem; max-width: 90vw; background: #fff; color: #16191d; border-radius: 12px;
+        box-shadow: 0 16px 40px -12px rgba(0,0,0,.35); border: 1px solid #e4e0d6; padding: .9rem; }
+      #${ROOT_ID}.open .panel { display: block; }
+      #${ROOT_ID} textarea { width: 100%; box-sizing: border-box; resize: vertical; min-height: 3.5rem;
+        border: 1px solid #d8d4c8; border-radius: 8px; padding: .5rem .6rem; font: inherit; }
+      #${ROOT_ID} .row { display: flex; gap: .4rem; margin-top: .5rem; }
+      #${ROOT_ID} button.primary { flex: 1; background: #0f7b6c; color: #fff; border: none;
+        border-radius: 8px; padding: .5rem .7rem; font: 600 .85rem/1 inherit; cursor: pointer; }
+      #${ROOT_ID} button.primary:disabled { opacity: .5; cursor: default; }
+      #${ROOT_ID} button.secondary { background: #ece9e0; color: #2a2d31; border: none;
+        border-radius: 8px; padding: .5rem .7rem; font: 600 .8rem/1 inherit; cursor: pointer; }
+      #${ROOT_ID} .status { margin-top: .6rem; font-size: .82rem; white-space: pre-wrap; }
+      #${ROOT_ID} .status.error { color: #a83a3a; }
+      #${ROOT_ID} .status.ok { color: #0f7b6c; }
+      #${ROOT_ID} details { margin-top: .5rem; }
+      #${ROOT_ID} pre { max-height: 12rem; overflow: auto; background: #16181d; color: #dbe3ea;
+        border-radius: 8px; padding: .5rem .6rem; font-size: .75rem; }
+    </style>
+    <button class="toggle" type="button" aria-label="Ask AI to edit this site" title="Ask AI to edit this site">✦</button>
+    <div class="panel">
+      <textarea placeholder="e.g. make it darker but still friendly" aria-label="Describe the change"></textarea>
+      <div class="row">
+        <button class="primary" type="button" data-action="ask">Ask</button>
+        <button class="secondary" type="button" data-action="undo">Undo last</button>
+      </div>
+      <div class="status" role="status" aria-live="polite"></div>
+    </div>
+  `;
+  document.body.appendChild(root);
+
+  const toggle = root.querySelector(".toggle");
+  const textarea = root.querySelector("textarea");
+  const askBtn = root.querySelector('[data-action="ask"]');
+  const undoBtn = root.querySelector('[data-action="undo"]');
+  const status = root.querySelector(".status");
+
+  toggle.addEventListener("click", () => root.classList.toggle("open"));
+
+  function setStatus(text, kind) {
+    status.textContent = text;
+    status.className = "status" + (kind ? " " + kind : "");
+  }
+
+  function renderResult(result) {
+    if (!result.ok) {
+      setStatus(result.message || `Refused (${result.status}).`, "error");
+      return;
+    }
+    if (result.status === "noop") {
+      setStatus(result.summary || "No change was needed.", "ok");
+      return;
+    }
+    setStatus(`✔ ${result.summary} — reloading…`, "ok");
+    // The file write already fires the existing content/theme HMR watch (see
+    // astro.config.mjs's tenantHotReload); nothing else to do here.
+  }
+
+  async function postJson(path, body) {
+    const res = await fetch(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body || {}),
+    });
+    return res.json();
+  }
+
+  askBtn.addEventListener("click", async () => {
+    const prompt = textarea.value.trim();
+    if (!prompt) return;
+    askBtn.disabled = true;
+    setStatus("Asking…");
+    try {
+      const result = await postJson("/__tot/ai-edit", { prompt });
+      renderResult(result);
+    } catch (e) {
+      setStatus(`Request failed: ${e.message}`, "error");
+    } finally {
+      askBtn.disabled = false;
+    }
+  });
+
+  undoBtn.addEventListener("click", async () => {
+    undoBtn.disabled = true;
+    setStatus("Undoing…");
+    try {
+      const result = await postJson("/__tot/ai-undo", {});
+      if (!result.ok) {
+        setStatus(result.message || "Nothing to undo.", "error");
+      } else {
+        setStatus(`↺ Reverted "${result.undid}" — reloading…`, "ok");
+      }
+    } catch (e) {
+      setStatus(`Request failed: ${e.message}`, "error");
+    } finally {
+      undoBtn.disabled = false;
+    }
+  });
+
+  textarea.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) askBtn.click();
+  });
+})();

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

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ */
+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. 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,
+  deps: { transport?: HttpTransport } = {},
+): 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() },
+    );
+  } 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}`;
+  // A single copy → a two-line paste that takes the developer all the way to a running
+  // store, no browser: line 1 signs the terminal in with the single-use code; line 2 checks
+  // out the store, runs it natively, and opens the browser on the working site — reusing the
+  // session line 1 just cached, so `start` never opens its own sign-in. Both lines use
+  // `npx @tokenoftrust/cli` (not bare `tot`): line 1 caches the package to the npx store, not
+  // onto PATH, so a bare `tot start` wouldn't resolve on a fresh machine.
+  //
+  // The trailing `&&` chains them: `start` runs ONLY if the code redeemed. Without it, a
+  // stale/burned code (single-use, short-TTL) would fail line 1 but line 2 would still run
+  // and fall back to `start`'s BROWSER sign-in — the exact surprise we're avoiding. With
+  // `&&`, an expired code stops with `login`'s clear "ask for a fresh invite" error instead.
+  const command = [
+    `npx @tokenoftrust/cli login --code ${payload.token}${mcpFlag} &&`,
+    `npx @tokenoftrust/cli start`,
+  ].join("\n");
+  return {
+    ok: true,
+    command,
+    expiresAt: payload.expiresAt ?? null,
+  };
+}

package/apps/storefront/src/lib/diag/redact.ts

@@ -0,0 +1,20 @@
+/**
+ * Redaction helpers for diagnostic logs — keep traces correlatable without persisting PII.
+ */
+
+/** Mask an email for logs: keep the first char + the domain (`d***@example.com`). */
+export function maskEmail(email: string): string {
+  const at = email.indexOf("@");
+  if (at <= 0) return "***";
+  return `${email[0]}***${email.slice(at)}`;
+}
+
+/**
+ * Email for a diagnostic line: the FULL address in local dev only (`import.meta.env.DEV`
+ * is a static boolean → this branch is tree-shaken from the production worker), where logs
+ * are local + gitignored and the raw address is needed for debugging; MASKED everywhere the
+ * build is deployed, so prod/worker logs never persist raw recipient PII.
+ */
+export function diagEmail(email: string): string {
+  return import.meta.env.DEV ? email : maskEmail(email);
+}

package/apps/storefront/src/lib/edgeCache.ts

@@ -0,0 +1,128 @@
+/**
+ * Full-page edge cache for production browse reads (Epic Phase-2 D1).
+ *
+ * Phase 1 cached only the catalog *API* calls (HttpToTClient); the rendered HTML
+ * was re-built on every request even though browse pages change rarely. This
+ * caches the final HTML response in the Workers Cache API and short-circuits the
+ * whole render on a hit.
+ *
+ * Invalidation is a per-tenant **cache version** integer in TENANT_CACHE KV. Bump
+ * it (see api/cache-purge.ts, called by the ETL after a re-migration) and every
+ * old key becomes unreachable — tag-like purge with no URL enumeration, and no
+ * dependency on Enterprise cache-tags. Stale keys age out on their own.
+ *
+ * Deliberately NOT cached: preview/test output (per-developer, noindex), any
+ * response with Set-Cookie, and anything non-200/non-HTML. In `astro dev` there
+ * is no `caches` global, so every helper is a clean no-op.
+ *
+ * Note on the CSP nonce: a stored page carries the nonce it was rendered with, in
+ * both its inline tags and its CSP header, and is served to many users. That is
+ * safe — the nonce is not a secret; it only has to match within one identical,
+ * non-personalized document, which it does.
+ */
+
+/** Synthetic internal origin for cache keys — never hits the network. */
+const CACHE_ORIGIN = "https://page-cache.tot.internal";
+const versionKey = (tenantId: string) => `cachever:${tenantId}`;
+
+/** Default freshness window (s-maxage) and stale window for cached pages. */
+const DEFAULT_TTL = 300;
+const DEFAULT_SWR = 86_400;
+
+/**
+ * Routes worth caching. Excludes the JSON typeahead (`?format=json`, high-q
+ * cardinality), `/api/*`, and anything with a preview token (handled upstream).
+ * Single-segment slugs (e.g. /about, /shipping-returns) cover editorial pages;
+ * non-200 responses are filtered at store time, so unknown slugs never persist.
+ */
+export function isCacheablePath(pathname: string, params: URLSearchParams): boolean {
+  if (params.get("format") === "json") return false;
+  if (pathname.startsWith("/api/")) return false;
+  // Authenticated operator surfaces are per-viewer and MUST NOT be edge-cached —
+  // the bare `/dashboard` index is a single-segment slug that would otherwise
+  // match the editorial-page rule below and be served across viewers.
+  if (pathname === "/dashboard" || pathname.startsWith("/dashboard/")) return false;
+  // `/dev` is the authenticated developer surface — per-viewer (it renders the
+  // signed-in developer's own store, email, and gated demo), so like /dashboard
+  // it must never be shared across viewers. It's also the loudest failure if
+  // stale: its styles build to a CONTENT-HASHED asset (/_astro/dev.<hash>.css),
+  // so a cached old HTML keeps pointing at a hash that no longer exists after the
+  // next deploy → the stylesheet 404s and the page renders unstyled (its inline
+  // nonce'd <script> tags break the same way). Never cache it.
+  if (pathname === "/dev") return false;
+  if (pathname === "/" || pathname === "/search") return true;
+  if (pathname.startsWith("/products/")) return true;
+  if (pathname.startsWith("/collections/")) return true;
+  return /^\/[a-z0-9][a-z0-9-]*\/?$/.test(pathname);
+}
+
+export function pageCacheKey(
+  tenantId: string,
+  pathname: string,
+  search: string,
+  version: number,
+): Request {
+  return new Request(`${CACHE_ORIGIN}/${tenantId}/v${version}${pathname}${search}`);
+}
+
+/** Current cache version for a tenant (defaults to 1). KV read is edge-cached. */
+export async function readCacheVersion(
+  kv: KVNamespace,
+  tenantId: string,
+): Promise<number> {
+  const raw = await kv.get(versionKey(tenantId), { cacheTtl: 60 });
+  const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n : 1;
+}
+
+/** Bump a tenant's cache version (logical purge of all its pages). Returns the new version. */
+export async function bumpCacheVersion(
+  kv: KVNamespace,
+  tenantId: string,
+): Promise<number> {
+  const next = (await readCacheVersion(kv, tenantId)) + 1;
+  await kv.put(versionKey(tenantId), String(next));
+  return next;
+}
+
+/** Return a cached page response (fresh clone), or null on miss. */
+export async function getCachedPage(
+  cache: Cache,
+  key: Request,
+): Promise<Response | null> {
+  const hit = await cache.match(key);
+  if (!hit) return null;
+  const res = new Response(hit.body, hit);
+  res.headers.set("X-ToT-Cache", "hit");
+  return res;
+}
+
+/**
+ * Store a rendered page if it is safe to cache. No-op for non-200, non-HTML, or
+ * cookie-bearing responses. Sets a public Cache-Control so any fronting CDN can
+ * help too. Caller passes the FINAL response (after CSP headers are set).
+ */
+export async function putCachedPage(
+  cache: Cache,
+  key: Request,
+  response: Response,
+  opts: { ttl?: number; swr?: number } = {},
+): Promise<void> {
+  if (response.status !== 200) return;
+  if (!(response.headers.get("content-type") ?? "").includes("text/html")) return;
+  if (response.headers.has("set-cookie")) return;
+
+  const ttl = opts.ttl ?? DEFAULT_TTL;
+  const swr = opts.swr ?? DEFAULT_SWR;
+  const cloned = response.clone();
+  const toStore = new Response(cloned.body, cloned);
+  toStore.headers.set(
+    "Cache-Control",
+    `public, s-maxage=${ttl}, stale-while-revalidate=${swr}`,
+  );
+  toStore.headers.set("X-ToT-Cache", "stored");
+  await cache.put(key, toStore).catch(() => void 0);
+}
+
+export const PAGE_CACHE_TTL = DEFAULT_TTL;
+export const PAGE_CACHE_SWR = DEFAULT_SWR;

package/apps/storefront/src/lib/email/magicLinkInviteEmail.ts

@@ -0,0 +1,62 @@
+/**
+ * The storefront's OWN branded developer-invite email (magic-link flow). The storefront
+ * owns presentation now — this is our template, our brand, rendered here and handed to
+ * tot20 only for transport (see lib/messaging/messagesClient.ts). A single primary CTA
+ * links to the GET-safe /auth/magic landing carrying the one-time token.
+ *
+ * Email HTML rules: inline styles only (no <style>/external CSS — mail clients strip them),
+ * table-free simple layout, and a visible fallback URL under the button (some clients don't
+ * render buttons). The token rides in the URL but is only consumed by a POST on the landing
+ * page, so a scanner GET can't burn it.
+ */
+
+/** Minimal HTML escape for untrusted interpolation (the inviter note). */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export interface MagicLinkInviteEmailInput {
+  /** The full magic-link URL (…/auth/magic?token=…) — already token-carrying. */
+  magicUrl: string;
+  /** Display name of the store/experience. Default "Regulated Storefront". */
+  storeName?: string;
+  /** Optional personal note from the inviter (untrusted → escaped). */
+  note?: string;
+}
+
+export function renderMagicLinkInviteEmail(input: MagicLinkInviteEmailInput): {
+  subject: string;
+  html: string;
+} {
+  const store = input.storeName?.trim() || "Regulated Storefront";
+  const subject = `Your invitation to ${store}`;
+  const url = input.magicUrl;
+  const note = input.note?.trim() ? esc(input.note.trim()) : null;
+
+  const html = `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
+  <body style="margin:0;padding:0;background:#f5f4f0;">
+    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#1c1c1c;">
+      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0f7b6c;margin:0 0 24px;">
+        Token of Trust&#169; &middot; ${esc(store)}
+      </div>
+      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.01em;margin:0 0 12px;color:#0b1f3a;">You've been invited</h1>
+      <p style="margin:0 0 8px;color:#3a3a3a;">You've been given developer access to <strong>${esc(store)}</strong>. Click below to sign in — no password needed.</p>
+      ${note ? `<div style="margin:16px 0;padding:12px 14px;background:#eef4ff;border:1px solid #c3d4f5;border-radius:8px;color:#234;font-size:14px;"><strong>Note from your inviter:</strong><br>${note}</div>` : ""}
+      <div style="margin:28px 0;">
+        <a href="${url}" style="display:inline-block;background:#0f7b6c;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:9px;">Sign in to ${esc(store)}</a>
+      </div>
+      <p style="margin:0 0 4px;font-size:13px;color:#6a6a6a;">Or paste this link into your browser:</p>
+      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${url}" style="color:#0f7b6c;">${url}</a></p>
+      <p style="margin:0;font-size:12px;color:#9a9a9a;border-top:1px solid #e6e4de;padding-top:16px;">This is a single-use sign-in link. If you didn't expect this invitation, you can ignore this email.</p>
+    </div>
+  </body>
+</html>`;
+
+  return { subject, html };
+}

package/apps/storefront/src/lib/env.ts

@@ -0,0 +1,60 @@
+/**
+ * Runtime env access that works in BOTH contexts:
+ *   - `astro dev` (Node): reads import.meta.env / process.env.
+ *   - Cloudflare Workers (prod): reads the `cloudflare:workers` env module.
+ *
+ * Astro v6+/@astrojs/cloudflare v14 REMOVED `Astro.locals.runtime.env`; the
+ * supported path is `import { env } from "cloudflare:workers"`. That module only
+ * exists in the worker runtime, so we import it lazily + guarded and fall back
+ * to build-time env in dev. See DECISIONS.md.
+ */
+import type { D1Like } from "./d1/catalog.js";
+
+let workerEnv: Record<string, unknown> | null | undefined;
+
+async function getWorkerEnv(): Promise<Record<string, unknown> | null> {
+  if (workerEnv !== undefined) return workerEnv;
+  try {
+    // @ts-expect-error — virtual module, only resolvable in the Workers runtime.
+    const mod = await import("cloudflare:workers");
+    workerEnv = (mod.env ?? null) as Record<string, unknown> | null;
+  } catch {
+    workerEnv = null;
+  }
+  return workerEnv;
+}
+
+function fromBuild(key: string): string | undefined {
+  const meta = import.meta.env as Record<string, string | undefined>;
+  if (meta[key] != null) return meta[key];
+  if (typeof process !== "undefined" && process.env && process.env[key] != null) {
+    return process.env[key];
+  }
+  return undefined;
+}
+
+export async function readEnv(key: string): Promise<string | undefined> {
+  const w = await getWorkerEnv();
+  const wv = w?.[key];
+  if (typeof wv === "string" && wv.length) return wv;
+  return fromBuild(key);
+}
+
+/** KV binding for the newsletter stub / tenant cache, if present in the runtime. */
+export async function readKv(binding: string): Promise<KVNamespace | undefined> {
+  const w = await getWorkerEnv();
+  const b = w?.[binding];
+  return (b as KVNamespace | undefined) ?? undefined;
+}
+
+/** D1 catalog binding for the edge read replica, if present in the runtime. */
+export async function readD1(binding: string): Promise<D1Like | undefined> {
+  const w = await getWorkerEnv();
+  return (w?.[binding] as D1Like | undefined) ?? undefined;
+}
+
+/** R2 bucket binding (e.g. TENANT_ASSETS, PRODUCT_IMAGES), if present. */
+export async function readR2(binding: string): Promise<R2Bucket | undefined> {
+  const w = await getWorkerEnv();
+  return (w?.[binding] as R2Bucket | undefined) ?? undefined;
+}