hexclave · BilalG1 · Apr 27, 2026 · Apr 24, 2026
diff --git a/apps/mock-oauth-server/src/index.ts b/apps/mock-oauth-server/src/index.ts
@@ -5,7 +5,7 @@ import Provider, { errors } from 'oidc-provider';
 
 const stackPortPrefix = process.env.NEXT_PUBLIC_STACK_PORT_PREFIX ?? "81";
 const defaultMockOAuthPort = Number(`${stackPortPrefix}14`);
-const port = Number(process.env.PORT ?? defaultMockOAuthPort);
+const port = Number(process.env.STACK_OAUTH_MOCK_PORT ?? process.env.PORT ?? defaultMockOAuthPort);
 const backendPortForRedirects = `${stackPortPrefix}02`;
 const emulatorBackendPort = process.env.STACK_EMULATOR_BACKEND_PORT ?? "32102";
 const providerIds = [

diff --git a/docker/local-emulator/qemu/cloud-init/emulator/user-data b/docker/local-emulator/qemu/cloud-init/emulator/user-data
@@ -130,6 +130,11 @@ write_files:
         HP_DASHBOARD="$STACK_EMULATOR_DASHBOARD_HOST_PORT"
         HP_MINIO="$STACK_EMULATOR_MINIO_HOST_PORT"
         HP_INBUCKET="$STACK_EMULATOR_INBUCKET_HOST_PORT"
+        # Mock OAuth binds to this port inside the VM and the host forwards the
+        # same port through, so the OIDC issuer URL is reachable identically
+        # from the browser and from the backend. Falls back to ${P}14 for
+        # older ISOs that don't set it.
+        HP_MOCK_OAUTH="${STACK_EMULATOR_MOCK_OAUTH_HOST_PORT:-${P}14}"
 
         cat <<COMPUTED
       STACK_SKIP_MIGRATIONS=true
@@ -153,7 +158,8 @@ write_files:
       STACK_CLICKHOUSE_URL=http://${DEPS_HOST}:8123
       STACK_EMAIL_MONITOR_VERIFICATION_CALLBACK_URL=http://localhost:${HP_DASHBOARD}/handler/email-verification
       STACK_EMAIL_MONITOR_INBUCKET_API_URL=http://${DEPS_HOST}:9001
-      STACK_OAUTH_MOCK_URL=http://localhost:${P}14
+      STACK_OAUTH_MOCK_URL=http://localhost:${HP_MOCK_OAUTH}
+      STACK_OAUTH_MOCK_PORT=${HP_MOCK_OAUTH}
       STACK_FREESTYLE_API_ENDPOINT=http://${DEPS_HOST}:8180
       STACK_STRIPE_MOCK_PORT=12111
       NEXT_PUBLIC_STACK_STRIPE_PUBLISHABLE_KEY=pk_test_mock_publishable_key_for_local_emulator

diff --git a/docker/local-emulator/qemu/run-emulator.sh b/docker/local-emulator/qemu/run-emulator.sh
@@ -35,6 +35,7 @@ EMULATOR_DASHBOARD_PORT="${EMULATOR_DASHBOARD_PORT:-26700}"
 EMULATOR_BACKEND_PORT="${EMULATOR_BACKEND_PORT:-26701}"
 EMULATOR_MINIO_PORT="${EMULATOR_MINIO_PORT:-26702}"
 EMULATOR_INBUCKET_PORT="${EMULATOR_INBUCKET_PORT:-26703}"
+EMULATOR_MOCK_OAUTH_PORT="${EMULATOR_MOCK_OAUTH_PORT:-26704}"
 
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -214,6 +215,7 @@ write_runtime_config_iso() {
     printf "STACK_EMULATOR_BACKEND_HOST_PORT=%s\n" "$EMULATOR_BACKEND_PORT"
     printf "STACK_EMULATOR_MINIO_HOST_PORT=%s\n" "$EMULATOR_MINIO_PORT"
     printf "STACK_EMULATOR_INBUCKET_HOST_PORT=%s\n" "$EMULATOR_INBUCKET_PORT"
+    printf "STACK_EMULATOR_MOCK_OAUTH_HOST_PORT=%s\n" "$EMULATOR_MOCK_OAUTH_PORT"
     printf "STACK_EMULATOR_VM_DIR_HOST=%s\n" "$vm_dir_host"
   } > "$cfg_dir/runtime.env"
   cp "$base_env" "$cfg_dir/base.env"
@@ -351,11 +353,12 @@ build_qemu_cmd() {
   netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_BACKEND_PORT}-:${PORT_PREFIX}02"
   netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_MINIO_PORT}-:9090"
   netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_INBUCKET_PORT}-:9001"
-  # Mock OAuth server: browser redirects land on `localhost:${PORT_PREFIX}14`
-  # (backend sets STACK_OAUTH_MOCK_URL to that value), so we forward host:port
-  # ↔ VM:port on the same number. Collides with pnpm dev, but the two modes
-  # are mutually exclusive.
-  netdev+=",hostfwd=tcp:127.0.0.1:${PORT_PREFIX}14-:${PORT_PREFIX}14"
+  # Mock OAuth server: the VM-internal mock binds to $EMULATOR_MOCK_OAUTH_PORT
+  # (overrides the pnpm-dev default of ${PORT_PREFIX}14 via STACK_OAUTH_MOCK_PORT
+  # threaded through runtime-config.iso). Host and guest use the same port so
+  # the OIDC issuer URL `http://localhost:${EMULATOR_MOCK_OAUTH_PORT}` resolves
+  # identically from the browser and from the backend inside the VM.
+  netdev+=",hostfwd=tcp:127.0.0.1:${EMULATOR_MOCK_OAUTH_PORT}-:${EMULATOR_MOCK_OAUTH_PORT}"
 
   # In snapshot-resume mode the QEMU command-line MUST match the device set
   # used at snapshot capture time, otherwise migration replay fails (broken
@@ -499,7 +502,7 @@ tail_vm_logs() {
 }
 
 ensure_ports_free() {
-  local ports=("$EMULATOR_DASHBOARD_PORT" "$EMULATOR_BACKEND_PORT" "$EMULATOR_MINIO_PORT" "$EMULATOR_INBUCKET_PORT" "${PORT_PREFIX}14")
+  local ports=("$EMULATOR_DASHBOARD_PORT" "$EMULATOR_BACKEND_PORT" "$EMULATOR_MINIO_PORT" "$EMULATOR_INBUCKET_PORT" "$EMULATOR_MOCK_OAUTH_PORT")
   local port
   for port in "${ports[@]}"; do
     if lsof -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
@@ -761,7 +764,7 @@ cmd_start() {
 
   info "Starting QEMU local emulator"
   info "Arch: $ARCH | Accel: $ACCEL"
-  info "Ports: Dashboard=$EMULATOR_DASHBOARD_PORT Backend=$EMULATOR_BACKEND_PORT MinIO=$EMULATOR_MINIO_PORT Inbucket=$EMULATOR_INBUCKET_PORT"
+  info "Ports: Dashboard=$EMULATOR_DASHBOARD_PORT Backend=$EMULATOR_BACKEND_PORT MinIO=$EMULATOR_MINIO_PORT Inbucket=$EMULATOR_INBUCKET_PORT MockOAuth=$EMULATOR_MOCK_OAUTH_PORT"
 
   local using_snapshot=0
   if snapshot_available; then

diff --git a/packages/stack-cli/src/commands/emulator.ts b/packages/stack-cli/src/commands/emulator.ts
@@ -14,6 +14,7 @@ const DEFAULT_EMULATOR_BACKEND_PORT = 26701;
 const DEFAULT_EMULATOR_DASHBOARD_PORT = 26700;
 const DEFAULT_EMULATOR_MINIO_PORT = 26702;
 const DEFAULT_EMULATOR_INBUCKET_PORT = 26703;
+const DEFAULT_EMULATOR_MOCK_OAUTH_PORT = 26704;
 const DEFAULT_PORT_PREFIX = "81";
 const GITHUB_API = "https://api.github.com";
 const DEFAULT_REPO = "stack-auth/stack-auth";
@@ -188,13 +189,15 @@ function prepareRuntimeConfigIso(): void {
   const backendPort = envPort("EMULATOR_BACKEND_PORT", DEFAULT_EMULATOR_BACKEND_PORT);
   const minioPort = envPort("EMULATOR_MINIO_PORT", DEFAULT_EMULATOR_MINIO_PORT);
   const inbucketPort = envPort("EMULATOR_INBUCKET_PORT", DEFAULT_EMULATOR_INBUCKET_PORT);
+  const mockOAuthPort = envPort("EMULATOR_MOCK_OAUTH_PORT", DEFAULT_EMULATOR_MOCK_OAUTH_PORT);
 
   const runtimeEnv = [
     `STACK_EMULATOR_PORT_PREFIX=${portPrefix}`,
     `STACK_EMULATOR_DASHBOARD_HOST_PORT=${dashboardPort}`,
     `STACK_EMULATOR_BACKEND_HOST_PORT=${backendPort}`,
     `STACK_EMULATOR_MINIO_HOST_PORT=${minioPort}`,
     `STACK_EMULATOR_INBUCKET_HOST_PORT=${inbucketPort}`,
+    `STACK_EMULATOR_MOCK_OAUTH_HOST_PORT=${mockOAuthPort}`,
     `STACK_EMULATOR_VM_DIR_HOST=${vmDir}`,
     "",
   ].join("\n");