emulator email-rendering, pck, and stripe fixes

hexclave · BilalG1 · Apr 14, 2026 · Mar 13, 2026 · Mar 19, 2026 · Apr 9, 2026
commit 11567e82b244f6e65f88c0a143edbee288913cf2
diff --git a/apps/backend/prisma/seed.ts b/apps/backend/prisma/seed.ts
@@ -101,6 +101,11 @@ export async function seed() {
       onboarding: {
         requireEmailVerification: false,
       },
+      ...(localEmulatorEnabled ? {
+        project: {
+          requirePublishableClientKey: false,
+        },
+      } : {}),
       dataVault: {
         stores: {
           'neon-connection-strings': {

diff --git a/apps/backend/src/app/api/latest/internal/local-emulator/project/route.tsx b/apps/backend/src/app/api/latest/internal/local-emulator/project/route.tsx
@@ -1,5 +1,5 @@
 import { Prisma } from "@/generated/prisma/client";
-import { overrideBranchConfigOverride } from "@/lib/config";
+import { overrideEnvironmentConfigOverride } from "@/lib/config";
 import {
   LOCAL_EMULATOR_ADMIN_USER_ID,
   LOCAL_EMULATOR_ONLY_ENDPOINT_MESSAGE,
@@ -100,6 +100,25 @@ async function getOrCreateLocalEmulatorProjectId(absoluteFilePath: string): Prom
     },
   });
 
+  const created = existingRow === undefined;
+
+  // Seed environment-level defaults BEFORE registering as a LocalEmulatorProject:
+  // once registered, setEnvironmentConfigOverride refuses to write.
+  //   - domains.allowLocalhost: fresh emulator projects allow localhost redirects
+  //     so developers don't hit "Redirect URL not whitelisted" before configuring
+  //     trustedDomains.
+  //   - payments.testMode: emulator payments always go through stripe-mock.
+  if (created) {
+    await overrideEnvironmentConfigOverride({
+      projectId,
+      branchId: DEFAULT_BRANCH_ID,
+      environmentConfigOverrideOverride: {
+        "domains.allowLocalhost": true,
+        "payments.testMode": true,
+      },
+    });
+  }
+
   await globalPrismaClient.$executeRaw(Prisma.sql`
     INSERT INTO "LocalEmulatorProject" ("absoluteFilePath", "projectId", "createdAt", "updatedAt")
     VALUES (${absoluteFilePath}, ${projectId}, NOW(), NOW())
@@ -109,7 +128,7 @@ async function getOrCreateLocalEmulatorProjectId(absoluteFilePath: string): Prom
       "updatedAt" = NOW()
   `);
 
-  return { projectId, created: existingRow === undefined };
+  return { projectId, created };
 }
 
 async function getOrCreateCredentials(projectId: string) {
@@ -219,20 +238,7 @@ export const POST = createSmartRouteHandler({
 
     await assertLocalEmulatorOwnerTeamReadiness();
 
-    const { projectId, created } = await getOrCreateLocalEmulatorProjectId(absoluteFilePath);
-    if (created) {
-      // Emulator projects are for local development. Default-allow localhost
-      // redirects so fresh projects don't hit "Redirect URL not whitelisted"
-      // before the developer has configured trustedDomains. User-supplied
-      // stack.config.ts still overrides this if they set domains explicitly.
-      await overrideBranchConfigOverride({
-        projectId,
-        branchId: DEFAULT_BRANCH_ID,
-        branchConfigOverrideOverride: {
-          "domains.allowLocalhost": true,
-        },
-      });
-    }
+    const { projectId } = await getOrCreateLocalEmulatorProjectId(absoluteFilePath);
     const credentials = await getOrCreateCredentials(projectId);
     const fileConfig = await readConfigFromFile(absoluteFilePath);
 

diff --git a/apps/backend/src/lib/ai/models.ts b/apps/backend/src/lib/ai/models.ts
@@ -1,3 +1,4 @@
+import { isLocalEmulatorEnabled } from "@/lib/local-emulator";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 import { getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
 
@@ -59,7 +60,7 @@ export const ALLOWED_MODEL_IDS: ReadonlySet<string> = new Set([
 ]);
 
 export function createOpenRouterProvider() {
-  const baseURL = getNodeEnvironment() === "development"
+  const baseURL = (getNodeEnvironment() === "development" || isLocalEmulatorEnabled())
     ? "http://localhost:8102/api/latest/integrations/ai-proxy/v1"
     : "https://api.stack-auth.com/api/latest/integrations/ai-proxy/v1";
   return createOpenRouter({

diff --git a/apps/backend/src/lib/js-execution.tsx b/apps/backend/src/lib/js-execution.tsx
@@ -1,6 +1,7 @@
 import { traceSpan } from '@/utils/telemetry';
 import { runAsynchronouslyAndWaitUntil } from '@/utils/background-tasks';
 import { getEnvVariable, getNodeEnvironment } from '@stackframe/stack-shared/dist/utils/env';
+import { isLocalEmulatorEnabled } from "@/lib/local-emulator";
 import { StackAssertionError, captureError } from '@stackframe/stack-shared/dist/utils/errors';
 import { Result } from '@stackframe/stack-shared/dist/utils/results';
 import { Sandbox } from '@vercel/sandbox';
@@ -27,11 +28,13 @@ function createFreestyleEngine(): JsEngine {
       let baseUrl = getEnvVariable("STACK_FREESTYLE_API_ENDPOINT", "") || undefined;
 
       if (apiKey === "mock_stack_freestyle_key") {
-        if (!["development", "test"].includes(getNodeEnvironment())) {
+        if (!["development", "test"].includes(getNodeEnvironment()) && !isLocalEmulatorEnabled()) {
           throw new StackAssertionError("Mock Freestyle key used in production; please set the STACK_FREESTYLE_API_KEY environment variable.");
         }
-        const prefix = getEnvVariable("NEXT_PUBLIC_STACK_PORT_PREFIX", "81");
-        baseUrl = `http://localhost:${prefix}22`;
+        if (!baseUrl) {
+          const prefix = getEnvVariable("NEXT_PUBLIC_STACK_PORT_PREFIX", "81");
+          baseUrl = `http://localhost:${prefix}22`;
+        }
       }
 
       const freestyle = new FreestyleClient({
@@ -147,7 +150,7 @@ export async function executeJavascript(code: string, options: ExecuteJavascript
 
       return await runWithFallback(code, options);
     } else {
-      if (getNodeEnvironment().includes("prod")) {
+      if (getNodeEnvironment().includes("prod") && !isLocalEmulatorEnabled()) {
         throw new StackAssertionError("STACK_VERCEL_SANDBOX_TOKEN is set to the disabled sentinel value in production. Please configure a real Vercel Sandbox token.");
       }
 

diff --git a/apps/backend/src/lib/payments.tsx b/apps/backend/src/lib/payments.tsx
@@ -7,19 +7,16 @@ import type { UsersCrud } from "@stackframe/stack-shared/dist/interface/crud/use
 import type { inlineProductSchema, productSchema, productSchemaWithMetadata } from "@stackframe/stack-shared/dist/schema-fields";
 import { SUPPORTED_CURRENCIES } from "@stackframe/stack-shared/dist/utils/currency-constants";
 import { FAR_FUTURE_DATE, addInterval, getIntervalsElapsed } from "@stackframe/stack-shared/dist/utils/dates";
-import { getEnvVariable, getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
 import { StackAssertionError, StatusError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
 import { filterUndefined, getOrUndefined, has, typedEntries, typedFromEntries, typedKeys, typedValues } from "@stackframe/stack-shared/dist/utils/objects";
 import { typedToUppercase } from "@stackframe/stack-shared/dist/utils/strings";
 import { isUuid } from "@stackframe/stack-shared/dist/utils/uuids";
 import Stripe from "stripe";
 import * as yup from "yup";
 import { Tenancy } from "./tenancies";
-import { getStripeForAccount } from "./stripe";
+import { getStripeForAccount, useStripeMock } from "./stripe";
 
 const DEFAULT_PRODUCT_START_DATE = new Date("1973-01-01T12:00:00.000Z"); // monday
-const stripeSecretKey = getEnvVariable("STACK_STRIPE_SECRET_KEY", "");
-const useStripeMock = stripeSecretKey === "sk_test_mockstripekey" && ["development", "test"].includes(getNodeEnvironment());
 
 type Product = yup.InferType<typeof productSchema>;
 type ProductWithMetadata = yup.InferType<typeof productSchemaWithMetadata>;

diff --git a/apps/backend/src/lib/stripe.tsx b/apps/backend/src/lib/stripe.tsx
@@ -8,15 +8,18 @@ import { getEnvVariable, getNodeEnvironment } from "@stackframe/stack-shared/dis
 import { captureError, StackAssertionError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
 import Stripe from "stripe";
 import type * as yup from "yup";
+import { isLocalEmulatorEnabled } from "./local-emulator";
 import { createStripeProxy, type StripeOverridesMap } from "./stripe-proxy";
 
 const stripeSecretKey = getEnvVariable("STACK_STRIPE_SECRET_KEY", "");
-const useStripeMock = stripeSecretKey === "sk_test_mockstripekey" && ["development", "test"].includes(getNodeEnvironment());
+export const useStripeMock = isLocalEmulatorEnabled()
+  || (stripeSecretKey === "sk_test_mockstripekey" && ["development", "test"].includes(getNodeEnvironment()));
 const stackPortPrefix = getEnvVariable("NEXT_PUBLIC_STACK_PORT_PREFIX", "81");
+const stripeMockPort = Number(getEnvVariable("STACK_STRIPE_MOCK_PORT", "") || `${stackPortPrefix}23`);
 const stripeConfig: Stripe.StripeConfig = useStripeMock ? {
   protocol: "http",
   host: "localhost",
-  port: Number(`${stackPortPrefix}23`),
+  port: stripeMockPort,
 } : {};
 
 /** Product type as stored in Stripe metadata (same as config product schema) */

diff --git a/docker/local-emulator/qemu/run-emulator.sh b/docker/local-emulator/qemu/run-emulator.sh
@@ -5,8 +5,8 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=common.sh
 source "$SCRIPT_DIR/common.sh"
 
-IMAGE_DIR="$SCRIPT_DIR/images"
-RUN_DIR="${EMULATOR_RUN_DIR:-$SCRIPT_DIR/run}"
+IMAGE_DIR="${EMULATOR_IMAGE_DIR:-$HOME/.stack/emulator/images}"
+RUN_DIR="${EMULATOR_RUN_DIR:-$HOME/.stack/emulator/run}"
 
 VM_RAM="${EMULATOR_RAM:-4096}"
 VM_CPUS="${EMULATOR_CPUS:-4}"

diff --git a/docker/server/entrypoint.sh b/docker/server/entrypoint.sh
@@ -26,7 +26,9 @@ else
 fi
 
 export NEXT_PUBLIC_STACK_PROJECT_ID=internal
-export NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=${STACK_SEED_INTERNAL_PROJECT_PUBLISHABLE_CLIENT_KEY}
+if [ "$NEXT_PUBLIC_STACK_IS_LOCAL_EMULATOR" != "true" ]; then
+  export NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=${STACK_SEED_INTERNAL_PROJECT_PUBLISHABLE_CLIENT_KEY}
+fi
 if [ -n "${STACK_SEED_INTERNAL_PROJECT_SECRET_SERVER_KEY:-}" ]; then
   export STACK_SECRET_SERVER_KEY=${STACK_SEED_INTERNAL_PROJECT_SECRET_SERVER_KEY}
 fi

diff --git a/packages/stack-cli/package.json b/packages/stack-cli/package.json
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "clean": "rimraf node_modules && rimraf dist",
-    "build": "tsdown",
+    "build": "tsdown && node scripts/copy-emulator-assets.mjs",
     "dev": "tsdown --watch",
     "lint": "eslint --ext .tsx,.ts .",
     "typecheck": "tsc --noEmit"

diff --git a/packages/stack-cli/scripts/copy-emulator-assets.mjs b/packages/stack-cli/scripts/copy-emulator-assets.mjs
@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { chmodSync, cpSync, mkdirSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const qemuSrc = resolve(packageRoot, "../../docker/local-emulator/qemu");
+const envSrc = resolve(packageRoot, "../../docker/local-emulator/.env.development");
+const distDir = join(packageRoot, "dist");
+const emulatorDist = join(distDir, "emulator");
+
+mkdirSync(emulatorDist, { recursive: true });
+
+for (const name of ["run-emulator.sh", "common.sh", "cloud-init"]) {
+  cpSync(join(qemuSrc, name), join(emulatorDist, name), { recursive: true });
+}
+
+chmodSync(join(emulatorDist, "run-emulator.sh"), 0o755);
+
+cpSync(envSrc, join(distDir, ".env.development"));
+
+console.log(`Copied emulator assets into ${emulatorDist} (+ .env.development into ${distDir}).`);
diff --git a/packages/stack-cli/src/commands/emulator.ts b/packages/stack-cli/src/commands/emulator.ts
@@ -1,7 +1,9 @@
 import { Command } from "commander";
 import { execFileSync, spawn } from "child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync } from "fs";
-import { join, resolve } from "path";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
 import { CliError } from "../lib/errors.js";
 
 const DEFAULT_EMULATOR_BACKEND_PORT = 26701;
@@ -16,8 +18,20 @@ function emulatorBackendPort(): number {
   return parsed;
 }
 
+function emulatorHome(): string {
+  return process.env.STACK_EMULATOR_HOME ?? join(homedir(), ".stack", "emulator");
+}
+
+function emulatorRunDir(): string {
+  return join(emulatorHome(), "run");
+}
+
+function emulatorImageDir(): string {
+  return join(emulatorHome(), "images");
+}
+
 function internalPckPath(): string {
-  return join(findQemuDir(), "run", "vm", "internal-pck");
+  return join(emulatorRunDir(), "vm", "internal-pck");
 }
 
 async function readInternalPck(timeoutMs = 60_000): Promise<string> {
@@ -79,39 +93,56 @@ function gh(args: string[]): string {
   }
 }
 
-function findQemuDir(): string {
-  for (const rel of ["docker/local-emulator/qemu", "../docker/local-emulator/qemu"]) {
-    const dir = resolve(process.cwd(), rel);
-    if (existsSync(join(dir, "run-emulator.sh"))) return dir;
-  }
-  throw new CliError("Could not find QEMU emulator directory. Run this from the stack-auth repo root.");
+function emulatorScriptsDir(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const bundled = join(here, "emulator");
+  if (existsSync(join(bundled, "run-emulator.sh"))) return bundled;
+  const repo = resolve(here, "../../../docker/local-emulator/qemu");
+  if (existsSync(join(repo, "run-emulator.sh"))) return repo;
+  throw new CliError("Emulator scripts not found in CLI bundle.");
+}
+
+function emulatorSpawnEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    EMULATOR_RUN_DIR: emulatorRunDir(),
+    EMULATOR_IMAGE_DIR: emulatorImageDir(),
+    ...extra,
+  };
 }
 
 function runEmulator(action: string, env?: Record<string, string>): Promise<void> {
-  const qemuDir = findQemuDir();
-  return new Promise((resolve, reject) => {
-    const child = spawn(join(qemuDir, "run-emulator.sh"), [action], {
+  const scriptsDir = emulatorScriptsDir();
+  mkdirSync(emulatorRunDir(), { recursive: true });
+  mkdirSync(emulatorImageDir(), { recursive: true });
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(join(scriptsDir, "run-emulator.sh"), [action], {
       stdio: "inherit",
-      env: { ...process.env, ...env },
-      cwd: qemuDir,
+      env: emulatorSpawnEnv(env),
+      cwd: scriptsDir,
     });
-    child.on("close", (code) => code === 0 ? resolve() : reject(new CliError(`run-emulator.sh ${action} exited with code ${code}`)));
+    child.on("close", (code) => code === 0 ? resolvePromise() : reject(new CliError(`run-emulator.sh ${action} exited with code ${code}`)));
     child.on("error", (err) => reject(new CliError(`Failed to run run-emulator.sh: ${err.message}`)));
   });
 }
 
 function isEmulatorRunning(): boolean {
-  const qemuDir = findQemuDir();
+  const scriptsDir = emulatorScriptsDir();
   try {
-    execFileSync(join(qemuDir, "run-emulator.sh"), ["status"], { stdio: "pipe", cwd: qemuDir });
+    execFileSync(join(scriptsDir, "run-emulator.sh"), ["status"], {
+      stdio: "pipe",
+      cwd: scriptsDir,
+      env: emulatorSpawnEnv(),
+    });
     return true;
   } catch {
     return false;
   }
 }
 
 async function startEmulator(arch: "arm64" | "amd64"): Promise<void> {
-  const img = join(findQemuDir(), "images", `stack-emulator-${arch}.qcow2`);
+  mkdirSync(emulatorImageDir(), { recursive: true });
+  const img = join(emulatorImageDir(), `stack-emulator-${arch}.qcow2`);
   if (!existsSync(img)) {
     console.log("No emulator image found. Pulling latest...");
     pullRelease(arch);
@@ -130,7 +161,7 @@ function pullRelease(arch: "arm64" | "amd64", opts: { repo?: string; branch?: st
   const branch = opts.branch ?? "dev";
   const tag = opts.tag ?? `emulator-${branch}-latest`;
   const asset = `stack-emulator-${arch}.qcow2`;
-  const imageDir = join(findQemuDir(), "images");
+  const imageDir = emulatorImageDir();
   mkdirSync(imageDir, { recursive: true });
   const dest = join(imageDir, asset);
   const tmpDest = `${dest}.download`;
@@ -172,7 +203,7 @@ export function registerEmulatorCommand(program: Command) {
           runId = String(runs[0].databaseId);
         }
 
-        const imageDir = join(findQemuDir(), "images");
+        const imageDir = emulatorImageDir();
         mkdirSync(imageDir, { recursive: true });
         const dest = join(imageDir, `stack-emulator-${arch}.qcow2`);
         if (existsSync(dest)) unlinkSync(dest);