- Updated vitest.config.ts to include a new alias for the TanStack Start server context, improving path resolution.
- Introduced a stub for the TanStack Start server context to streamline server context handling.
These changes enhance the integration of TanStack Start by improving the Vite configuration and server context management.
- Added new environment variables for Vite in the dashboard V2 `.env.development` file.
- Updated `pnpm-lock.yaml` to include new dependencies for TanStack Start and React Query.
- Enhanced the routing setup in `router.tsx` to integrate React Query with TanStack Router.
- Refactored the `routeTree.gen.ts` to include new routes for the dashboard V2.
- Updated the design guide and documentation for dashboard V2 components and layout.
- Added new SVG assets for branding and social previews in the public directory.
- Adjusted ESLint configuration to relax rules for generated components.
- Improved the `.gitignore` to include the new `tanstack-start` package directory.
- Refactored package.json and tsconfig.json in the TanStack Start demo to streamline dependencies and improve path resolution.
- Updated Vite configuration to remove unnecessary imports and enhance clarity.
- Introduced new server context files to manage cookies and request headers more effectively.
- Enhanced cookie management in the template library to support dynamic imports for TanStack Start server APIs.
- Improved the overall structure and organization of the TanStack Start integration, ensuring better compatibility and performance.
These changes enhance the integration of TanStack Start, improve server context handling, and streamline the development experience.
- Updated the default not found component in the TanStack Start demo to provide a user-friendly 404 page.
- Refactored the Header component to use a client-mounted UserButton for better rendering performance.
- Improved cookie handling in the template library to support dynamic imports for TanStack Start server APIs.
- Added a new function to retrieve the server request host, enhancing compatibility with different platforms.
These changes improve the overall integration of TanStack Start, enhance user experience, and ensure better performance across the application.
- Removed the deprecated tanStackStartServerBrowserStub function from the Vite configuration.
- Updated cookie management in the cookie.ts file to support dynamic imports for TanStack Start server APIs.
- Enhanced createCookieHelper to conditionally use TanStack Start's cookie methods based on the SSR environment.
- Adjusted createTanStackStartCookieHelper to accept the server API as a parameter for better modularity.
These changes streamline the integration of TanStack Start, improving cookie management and ensuring compatibility with server-side rendering.
- Added a new icon for TanStack Start in the app-card component.
- Updated APP_URL_OVERRIDES to include a link for TanStack Start documentation.
- Modified styles.css to enable stylelint for SCSS at-rules.
These changes enhance the integration of TanStack Start within the application, improving both functionality and documentation accessibility.
- Updated package.json scripts to include the new TanStack Start demo.
- Added a new logo for TanStack Start in the dashboard.
- Enhanced sidebar navigation to support external links for documentation.
- Introduced new environment keys for Vite integration.
- Created comprehensive setup instructions for TanStack Start in the documentation.
- Added example project for TanStack Start to showcase integration with Stack Auth.
This commit improves the developer experience by providing clear guidance and resources for integrating Stack Auth with TanStack Start applications.
## Summary
- Route browser OAuth redirects through the configured `redirectMethod`
instead of hardcoded `window.location` calls.
- Keep OAuth redirect APIs pending after navigation starts, including
custom redirect methods.
- Add `cliAuthConfirm` handler URL metadata and custom-page prompt
coverage.
- Update SDK spec text for browser OAuth callback and `returnTo`
behavior.
## Root Cause
OAuth helpers previously combined URL construction with direct browser
navigation. That bypassed configured redirect methods and made it too
easy for public redirect APIs to resolve after navigation started.
## Impact
Browser SDK consumers get consistent redirect behavior across built-in
and custom navigation methods. `returnTo` is handled as the
post-callback destination while the OAuth callback URL remains fixed to
the configured handler route.
## Validation
- `pnpm test run packages/template/src/lib/auth.test.ts`
- `pnpm test run apps/e2e/tests/js/oauth.test.ts`
- `pnpm -C packages/template lint`
- `pnpm -C apps/e2e lint`
- `pnpm -C packages/template typecheck`
- `pnpm -C apps/e2e typecheck`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added CLI authorization confirmation page/flow for terminal-based
auth.
* Added optional returnTo parameter for OAuth to control post-auth
redirects.
* Exposed configurable redirect behavior so apps follow the chosen
redirect method.
* **Bug Fixes**
* OAuth callback now uses app navigation/queued redirects and shows a
fallback link instead of forcing location.assign.
* **Tests**
* Added unit and e2e tests covering OAuth URL generation, scope
handling, and CLI auth confirmation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
# Shareable Session Replay Links
Adds the ability to share individual session replays via unique, direct
URLs.
https://www.loom.com/share/1e3298a19b114fc38af4bc43dcd5ec48
## What changed
- New admin endpoint — GET /api/v1/internal/session-replays/:id
- Fetches a single session replay by ID with user metadata (display
name, primary email) and chunk/event counts
- Returns 404 if the replay doesn't exist
- Admin-only access, consistent with the existing list endpoint
## New standalone replay page —
/projects/:projectId/analytics/replays/:replayId
- Thin server page wrapper that passes the replay ID to the existing
PageClient
- PageClient detects standalone mode via initialReplayId prop and
fetches replay metadata directly instead of loading the full session
list
- Sidebar is hidden; the replay viewer takes the full width
- "Back to all replays" link shown under the page title
## Copy link button
- Moved from per-session sidebar items to the replay viewer header (next
to the settings gear)
- Copies a direct URL to the currently selected replay
## SDK plumbing
- AdminGetSessionReplayResponse type in stack-shared
- getSessionReplay() on StackAdminInterface, StackAdminApp interface,
and _StackAdminAppImplIncomplete
## Tests
- Happy path: fetch single replay by ID with inline snapshot
- 404 for nonexistent replay ID
- 401 for non-admin access (client and server)
## Test plan
- [ ] Open /analytics/replays, select a replay, click the link icon in
the header — verify URL is copied to clipboard
- [ ] Paste that URL in a new tab — verify the standalone replay page
loads and plays the correct replay
- [ ] Verify "Back to all replays" link navigates back to the list page
- [ ] Verify the original /analytics/replays list page still works as
before (selecting, filtering, pagination)
- [ ] Run pnpm test run session-replays
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Backend: internal endpoint to fetch a single session replay with user
info, millisecond timestamps, and chunk/event counts.
* Admin SDK/App: added response type and admin method to retrieve a
single session replay; admin app maps response into the app model.
* Dashboard: standalone session-replay page, UI adjustments for
standalone mode, and a “copy replay link” button.
* **Tests**
* Added end-to-end tests for retrieval, not-found, and access-control
scenarios.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- Extract CLI auth confirmation into a `useCliAuthConfirmation()` hook
(status / error / isLoading / authorize / retry) so custom pages don't
have to reimplement the protocol; `CliAuthConfirmation` now consumes the
hook.
- Make `cliAuthConfirm` a first-class handler URL target — resolved via
`resolveHandlerUrls`, customizable per project, and used by
`promptCliLogin` through a new `buildCliAuthConfirmUrl()` helper.
- Move `StackContext` to its own module so the hook can be unit-tested
with a test double without tripping the client-version sentinel;
register `cliAuthConfirm` in custom-page prompts and the dev-tool
components tab; export the hook + types from `@stackframe/stack`.
## Test plan
- [ ] `pnpm typecheck`
- [ ] `pnpm lint`
- [ ] `pnpm --filter @stackframe/stack test cli-auth-confirm
url-targets`
- [ ] Manually verify default `/handler/cli-auth-confirm` flow + a
project with a custom `cliAuthConfirm` URL
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Adds a CLI authentication confirmation page with clear states
(invalid, authorizing, redirecting, success, error), retry action, and
flows for signed-in and anonymous users.
* CLI login URL generation now derives from the configured handler
target and app base, improving reliability.
* CLI confirmation page exposed in the components/dev UI for previewing.
* **Tests**
* End-to-end and unit tests covering confirmation behaviors and URL
generation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- Bare `process.env.X` accesses in `stack-shared` throw `ReferenceError:
process is not defined` when the package is bundled into a browser app
without a `process` shim (e.g. a plain Vite app). The most reachable
offenders are in `StackAssertionError`'s constructor and
`schema-fields.ts`'s Neon Basic-auth validator, both of which can run on
the client during normal sign-in flows with `@stackframe/react`.
- Extracted a zero-dependency `getProcessEnv` helper at
`packages/stack-shared/src/utils/process-env.tsx` and routed the bare
references through it. Returns `undefined` when `process` is not
defined; otherwise behaves like a normal `process.env[name]` read, so
Next.js/webpack inlining is unchanged on the server.
- Touched: `schema-fields.ts:884` (`STACK_INTEGRATION_CLIENTS_CONFIG`),
`utils/errors.tsx:81` (`NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR`),
`utils/promises.tsx` (`NODE_ENV` in `runAsynchronouslyWithAlert`),
`utils/esbuild.tsx:16` (`NODE_ENV`, also reordered the `typeof process`
guard so the env access is unreachable in browsers).
## Why a separate helper module
`utils/env.tsx` already exists but its `getEnvVariable` explicitly
throws in the browser, so it can't be reused here. The new module has
zero imports so it can be safely consumed from low-level utilities like
`errors.tsx` without creating a cycle (env.tsx ↔ errors.tsx).
## Test plan
- [x] `pnpm lint` passes
- [x] `pnpm typecheck` passes
- [ ] Reproduced the original failure in a Vite + `@stackframe/react`
app: sign-in flow logged `ReferenceError: process is not defined` from
`StackAssertionError`, plus `clientSecret must not be empty` cascading
from the same path
- [ ] Verify the same flow in a Vite app no longer throws once
`@stackframe/react` is rebuilt against this `stack-shared` change
- [ ] Confirm Next.js consumer behavior is unchanged (env vars still
inlined at build time for `NEXT_PUBLIC_*`)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Refactor**
* Improved environment variable handling across shared utilities for
enhanced browser compatibility and safety. Introduced a new utility for
dynamic, browser-safe environment variable access that prevents errors
in non-Node.js environments.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Updated package versions in pnpm-lock.yaml, including `react-dom` and `lightningcss`.
- Added new dependencies for the dashboard application, including various UI and utility libraries.
- Enhanced the `GET` route for feature flags to support additional response types and improved validation.
- Refactored the `POST` route to streamline user ID handling and ensure consistent behavior.
- Updated tests to reflect changes in API behavior and ensure proper request handling.
- Implemented `evaluateFeatureFlags` method in `StackClientInterface` to handle feature flag evaluations via the API.
- Added corresponding tests for feature flag evaluation in `client-interface.test.ts` to ensure correct request handling and response validation.
- Introduced new types for feature flag requests and responses in `feature-flags.ts` to standardize data structures.
- Enhanced the `StackClientApp` interface with methods for retrieving single and multiple feature flags, including React hooks for integration.
- Updated documentation to reflect new feature flag functionalities and usage examples.
- Updated regex condition handling in feature flags to ensure valid patterns are enforced.
- Enhanced the evaluation logic to handle distinct user IDs and server-side context more effectively.
- Improved response structure for feature flag evaluations, including support for conditional headers and optimized payloads.
- Adjusted the default state of feature flags in the dashboard to be disabled.
- Added comprehensive tests for new evaluation scenarios and response behaviors.
Definitions live in branch config (free branch/env overrides). Pure
deterministic evaluator shared by backend and (future) SDKs, MurmurHash3
bucketing, kill switch, dependsOn, holdouts, weighted multivariate.
Adds /feature-flags/{bootstrap,evaluate} routes, dashboard CRUD, seed
data, and an example demo page.
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
## Summary
- `stack emulator pull` now preflights VM dependencies (QEMU binaries,
socat/curl/nc/lsof/openssl/zstd, and aarch64 UEFI firmware on arm64)
before downloading.
- Missing deps are listed, then installed with user confirmation via
`brew` on macOS (bootstrapping Homebrew itself if absent) or `sudo
apt-get` on Linux.
- Skipped when `--skip-snapshot` is passed, since that path never boots
the VM.
- `gh` / `GITHUB_TOKEN` are intentionally excluded from the auto-install
set.
## Test plan
- [ ] `node packages/stack-cli/dist/index.js emulator pull` on a machine
with all deps present → no prompt, proceeds as before.
- [ ] Unlink a dep (e.g. `brew unlink zstd`) and rerun → missing dep
listed, decline prompt → exits with a clear error; accept prompt → brew
install runs and pull continues.
- [ ] `emulator pull --skip-snapshot` still bypasses the dep check.
- [ ] Linux path: missing binaries trigger `sudo apt-get update && sudo
apt-get install -y …`.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Emulator pull now detects missing host dependencies and, on
macOS/Linux with an interactive terminal and supported package tools,
shows a proposed install plan, prompts for confirmation, and can
auto-install required packages (including optional ARM64 firmware).
Homebrew will be bootstrapped if absent.
* Use --skip-snapshot to bypass the interactive dependency check and
installation.
* **Behavior**
* In non-interactive or unsupported environments, the tool falls back to
the prior preflight behavior instead of attempting installation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a "create-cloud" mode to the CLI init flow.
* New interactive project creation flow that can prompt for display name
and select/create a team-backed project.
* **Behavior Changes**
* Init now resolves mode from flags, config, or interactive prompts;
prompts to choose linking vs creating when inputs are missing.
* Non-interactive runs now error when required inputs are absent; cloud
linking offers auto-create in interactive mode.
* **Refactor**
* Centralized auth, project-creation, and env key writing for clearer,
safer linking and creation flows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: aadesh18 <110230993+aadesh18@users.noreply.github.com>
## Summary
- The emulator's mock OAuth server bound to `${PORT_PREFIX}14` (8114)
inside the VM and the host forwarded the same port, colliding with `pnpm
dev`'s mock-oauth-server on 8114.
- Moves the emulator's mock OAuth to `EMULATOR_MOCK_OAUTH_PORT` (default
`26704`, joining the existing `267xx` host port block) and binds the
VM-internal mock to the same port. Same port on both sides keeps the
OIDC issuer URL (`http://localhost:26704`) resolvable identically from
the browser and from the backend inside the VM.
- Plumbed via `runtime-config.iso` as
`STACK_EMULATOR_MOCK_OAUTH_HOST_PORT`, read by cloud-init into
`STACK_OAUTH_MOCK_URL` + new `STACK_OAUTH_MOCK_PORT`;
`mock-oauth-server` now prefers `STACK_OAUTH_MOCK_PORT` so `pnpm dev`
(which doesn't set it) stays on 8114.
## Files
- `docker/local-emulator/qemu/run-emulator.sh` — new
`EMULATOR_MOCK_OAUTH_PORT`, hostfwd/ensure_ports_free/runtime.env
updates
- `docker/local-emulator/qemu/cloud-init/emulator/user-data` — reads the
host port, sets `STACK_OAUTH_MOCK_URL` + `STACK_OAUTH_MOCK_PORT`
- `apps/mock-oauth-server/src/index.ts` — honors `STACK_OAUTH_MOCK_PORT`
- `packages/stack-cli/src/commands/emulator.ts` — default + runtime.env
entry
## Test plan
- [ ] `pnpm emulator:build` succeeds and new snapshot boots
- [ ] `stack emulator start` with `pnpm dev` running on 8114 — no port
collision
- [ ] OAuth sign-in via mock provider completes end-to-end in the
emulator
- [ ] `pnpm dev` mock OAuth unchanged (still 8114)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **New Features**
* The mock OAuth server port is now configurable in the local emulator
with a sensible default, allowing custom port assignments via
environment variable.
* **Improvements**
* Updated port forwarding and environment variable handling to ensure
consistent mock OAuth endpoint configuration across host and guest
systems in the emulator.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- The init prompt marked the `StackProvider` step as *React only* and
placed it after the `StackHandler` step. Following it on a Next.js
project produced a layout with no provider, so `StackHandler` crashed at
runtime with `useStackApp must be used within a StackProvider`.
- Make the provider step unconditional and move it ahead of the handler
step so the dependency order matches the instruction order. Also quote
the exact error message so the model won't skip it.
## Test plan
- [ ] Run `npx @stackframe/stack-cli init` (or the web flow) against a
fresh Next.js app and confirm `/handler/[...stack]` renders without the
`useStackApp` error.
- [ ] Re-run against a Vite/React app to confirm the reordered
instructions still produce a working setup.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added explicit global MCP config file path guidance for several coding
agents.
* Documented required provider configuration across supported
frameworks.
* Clarified where to place provider wrappers in root app layouts
(including Next.js app/layout).
* Reordered setup steps to surface the required "Wrap your app in a
Stack provider" step and updated step numbering.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What changed
This fixes Sentry issue
[STACK-BACKEND-1A3](https://stackframe-pw.sentry.io/issues/7436639623/?project=4507442898272256&query=is%3Aunresolved&referrer=issue-stream&seerDrawer=true).
A request with this malformed header:
```http
Authorization: Basic
```
used to crash the Neon auth validator with a `StackAssertionError`,
which turned a bad client request into a 500.
The fix makes `neonAuthorizationHeaderSchema` only validate Neon client
credentials after the Basic auth header successfully decodes. If
decoding fails, the Neon-specific validator returns `true` and lets
`basicAuthorizationHeaderSchema` produce the intended 400 schema error:
`Authorization header must be in the format "Basic <base64>"`.
## Reviewer walkthrough
There are two checks chained together:
1. `basicAuthorizationHeaderSchema` checks that the header is
structurally valid Basic auth.
2. `neonAuthorizationHeaderSchema` checks that the decoded
`client_id:client_secret` matches a configured Neon client.
Yup may still run the second check after the first one has failed,
because route validation collects errors with `abortEarly: false`. The
old code assumed the first check had already passed and called
`throwErr(...)` when decoding returned `null`. This PR changes that path
to return `true`, because the format error is already owned by the first
check.
## Tests
- `pnpm -C packages/stack-shared exec vitest run --maxWorkers=1
--minWorkers=1 src/schema-fields.ts`
- `pnpm -C apps/e2e exec vitest run --maxWorkers=1 --minWorkers=1
tests/backend/endpoints/api/v1/integrations/neon/projects/transfer.test.ts
-t "malformed"`
- `pnpm -C packages/stack-shared lint`
- `pnpm -C packages/stack-shared typecheck`
- `pnpm -C apps/e2e lint`
- `pnpm -C apps/e2e typecheck`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Enhanced authorization header validation in API endpoints with
improved error handling, ensuring malformed credentials return clear,
specific validation error messages.
* **Tests**
* Added comprehensive end-to-end test coverage for API request
validation, including edge cases for authorization headers.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
`stack emulator start` now resumes a fully-warm VM snapshot instead of
cold-booting, bringing startup from 30–120s down to ~5–8s with
per-install secret rotation, or ~2.5s with rotation opt-out. The
snapshot is captured **locally on first `stack emulator pull`**, not
shipped from CI — QEMU migration state isn't portable across
accelerators (KVM/HVF/TCG) or `-cpu max` feature sets, so a CI-captured
snapshot couldn't resume reliably on arbitrary user hardware.
Also bundles a pile of CLI QoL fixes (progress bars, PR/run artifact
pulls, PR-build download, native-TS ISO writer replacing
`hdiutil`/`mkisofs`/`genisoimage` host dep, unit tests).
| Scenario | Before | After |
|---|---|---|
| Cold boot (no snapshot) | 30–120s | same, works as fallback |
| `stack emulator pull` (one-time, includes local snapshot capture) |
~30s download | ~30s download + ~1–3 min cold-boot capture |
| Snapshot resume, normal start | — | **~5–8s** |
| Snapshot resume, `EMULATOR_NO_ROTATION=1` | — | **~2.5s** |
Backend (`/health?db=1`) and dashboard (`/handler/sign-in`) return 200
on all paths. Two successive snapshot resumes produce different rotated
PCK/SSK/SAK/CRON_SECRET values per install.
## How it works
**Build (CI)** — `docker/local-emulator/qemu/build-image.sh`:
1. Cloud-init provisioning runs to completion (migrations, seed,
slim-image) producing `stack-emulator-<arch>.qcow2`.
2. Image is built with a topology compatible with later snapshot capture
(pinned SMP=4, phantom seed/bundle ISOs, STACKCFG runtime ISO mounted at
build time, qemu-guest-agent running, placeholder hex secrets baked in
under `STACK_EMULATOR_BUILD_SNAPSHOT=1`).
3. CI publishes **only the qcow2** — no `.savevm.zst` ships.
**Pull (user's machine)** —
`packages/stack-cli/src/commands/emulator.ts` + `run-emulator.sh
capture`:
1. `stack emulator pull` downloads the qcow2 with a progress bar (or
from a PR / workflow run via `--pr` / `--run`).
2. CLI invokes `run-emulator.sh capture`: cold-boots the qcow2 with a
matching device layout (phantom ISOs, fsdev, pcie-root-port, virtfs
detached — migration-incompatible), waits for backend+dashboard health,
then drives QMP: `stop` → set `mapped-ram` + `multifd` caps → `migrate
file:state.raw` → poll `query-migrate` → `quit`. Raw mapped-ram file is
zstd-compressed to `stack-emulator-<arch>.savevm.zst` in the images dir.
3. `--skip-snapshot` opts out (first `start` will then cold-boot).
**Runtime** — `run-emulator.sh start`:
1. Launch QEMU with `-incoming defer` when a `.savevm.zst` is present;
decompress on first use, keep the `.raw` cached for subsequent starts.
2. QMP: same `mapped-ram` + `multifd` caps → `migrate-incoming
file:<.raw>` → poll for `paused` → `cont`.
3. Generate fresh per-install secrets on the host; pipe them
base64-encoded through QGA `guest-exec input-data` →
`trigger-fast-rotate` in the guest → `docker exec -e … rotate-secrets`.
4. `rotate-secrets` in the container: validate keys (hex-only), targeted
`sed` on the placeholder PCK across built JS, `UPDATE ApiKeySet`,
`supervisorctl restart stack-app cron-jobs` (with
`stopasgroup`/`killasgroup` so the Node children actually die and
release their ports).
5. Poll backend+dashboard health; if anything fails, clean up and fall
back to cold boot transparently.
**Security model**: placeholder hex values are baked into the snapshot
(`00…ff` PCK, `00…ee` SSK, `00…dd` SAK, `00…cc` CRON_SECRET). They are
non-secret by construction. Real per-install secrets are generated at
each `emulator start` and never leave the host.
## CLI changes (`packages/stack-cli`)
- **`src/lib/iso.ts`** (new): native TypeScript ISO 9660 + Joliet
writer, replacing the host-side `hdiutil`/`mkisofs`/`genisoimage`
dependency for generating the STACKCFG runtime config disk. Unit tests
in `src/lib/iso.test.ts`.
- **`src/commands/emulator.ts`**:
- `pull`: streamed downloads with progress bar + ETA; `--pr <number>`
and `--run <id>` to pull from a PR build's CI artifacts (uses
`extract-zip` for the nested zip); `--skip-snapshot` to opt out of the
one-time local capture.
- `start` (existing, extended): auto-pulls AND auto-captures when no
image exists, so first-ever `start` is self-bootstrapping; emits
`STACK_EMULATOR_CLI_WROTE_ISO=1` so the shell helper skips its own ISO
regen (avoids the genisoimage host dep).
- `capture` (new, invoked by `pull` and the auto-pull path of `start`):
drives the local snapshot capture via `run-emulator.sh`.
- `status`, `stop`, `reset`, `list-releases`: preflight +
path-resolution tightening (`STACK_EMULATOR_HOME` → images/run dirs).
- Unit tests in `src/commands/emulator.test.ts`.
- **`EMULATOR_NO_ROTATION=1`** env var skips the post-resume rotation
(intended for tests/CI where the placeholder secrets are fine — comes
with a loud warning).
## CI (`.github/workflows/qemu-emulator-build.yaml`)
- Builds **QEMU 10.2.2 from source** (cached), because
`mapped-ram`/`multifd` migration capabilities aren't available in the
distro's QEMU. Enables KVM on ubicloud runners so amd64 boots at
hardware speed.
- amd64 + arm64 both build on the same amd64 matrix
(`ubicloud-standard-8`); arm64 runs under cross-arch TCG (provisioning
only — boot/verify smoke test is amd64-only).
- Verification now runs through the CLI: `emulator start` → `emulator
status` → `emulator stop` against the freshly-built qcow2 (via
`STACK_EMULATOR_HOME` pointing at the workspace, so the CLI doesn't
silently auto-pull a prior release).
- Packages **only** the qcow2. No `.savevm.zst` upload / publish.
- Release notes updated.
## Key files
**Shell / guest:**
- `docker/local-emulator/qemu/build-image.sh` — snapshot-compatible
device topology + STACKCFG runtime ISO at build time
- `docker/local-emulator/qemu/run-emulator.sh` — `start`, `capture`,
`stop`, `reset`, `status`; `-incoming defer`, `.raw` cache, QGA-driven
rotation, cold-boot fallback
- `docker/local-emulator/qemu/common.sh` (new) — shared `qmp_session` +
`capture_vm_state` (factored out so build-image.sh and run-emulator.sh
share the capture path)
- `docker/local-emulator/qemu/cloud-init/emulator/user-data` —
placeholder secrets in snapshot mode, `wait-for-stack-ready`,
`trigger-fast-rotate`, qemu-guest-agent enabled
- `docker/local-emulator/rotate-secrets.sh` (new) — in-container
rotation (sed + UPDATE + supervisorctl)
- `docker/local-emulator/supervisord.conf` — `stopasgroup`/`killasgroup`
on `stack-app` and `cron-jobs`
- `docker/local-emulator/entrypoint.sh` — only mint CRON_SECRET if unset
(placeholder supplied in snapshot mode via --env-file)
- `docker/local-emulator/Dockerfile` — ships `rotate-secrets` to
`/usr/local/bin`
- `docker/server/entrypoint.sh` — source
`/run/stack-auth/rotated-secrets.env`; skip full-tree sentinel scan on
warm restarts via marker
**CLI:**
- `packages/stack-cli/src/lib/iso.ts` (new) + `iso.test.ts` (new)
- `packages/stack-cli/src/commands/emulator.ts` + `emulator.test.ts`
(new)
- `packages/stack-cli/vitest.config.ts` (new)
**CI:**
- `.github/workflows/qemu-emulator-build.yaml`
## Test plan
- [x] `docker/local-emulator/qemu/build-image.sh {amd64,arm64}` produces
`stack-emulator-<arch>.qcow2` with snapshot-compatible topology
- [x] `stack emulator pull` downloads qcow2 with progress, then captures
locally (~1–3 min) and writes `stack-emulator-<arch>.savevm.zst` in the
images dir
- [x] `stack emulator pull --skip-snapshot` stops after download
- [x] `stack emulator pull --pr <n>` / `--run <id>` pull from PR /
workflow run artifacts
- [x] `stack emulator start` on a fresh dir auto-pulls **and**
auto-captures, then starts; subsequent starts fast-resume in ~5–8s;
backend + dashboard return 200
- [x] `EMULATOR_NO_ROTATION=1 stack emulator start` completes in ~2.5s;
backend + dashboard return 200 with warning printed
- [x] Two consecutive `emulator start` invocations produce different PCK
values in the internal `ApiKeySet` row
- [x] `stack emulator status` / `stop` / `reset` resolve paths from
`STACK_EMULATOR_HOME`
- [x] Verified end-to-end on arm64 macOS under HVF (capture ~50s,
fast-resume ~6.5s)
- [x] `pnpm lint` and `pnpm typecheck` pass; stack-cli unit tests (iso +
emulator) pass
- [ ] CI green on this PR (qemu-emulator-build matrix, smoke test)
- [ ] `gh release download emulator-<branch>-latest` contains only
`stack-emulator-<arch>.qcow2` once this PR merges and publish runs
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Snapshot fast-start/resume with optional warm-snapshot assets, runtime
ISO generation, and a cached QEMU build to speed emulator setup.
* CLI: streamed artifact downloads with progress, improved release/asset
handling, stronger preflight checks, and start/status/stop emulator
commands.
* Automated secret rotation and ability to apply rotated secrets at
container startup; supervisor control socket enabled.
* **Bug Fixes**
* More robust start/stop/resume flows with automatic fallback to cold
boot and improved process-group shutdown behavior.
* **Tests**
* New tests for CLI utilities and ISO image generation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Request sanitization now includes an extra proxy-specific
preprocessing step for safer AI proxying.
* **New Features**
* Initialization prompts centralized into a shared helper, with a
web-specific prompt variant.
* Authenticated requests can optionally route via a provided external
API key to access alternate models.
* **Chores**
* Added and exposed a preprocessing hook with a default no-op
implementation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
### Object of this PR
This PR is NOT a monolithic series of fixes for the payments suite + a
complete rework. Its aims were
a) introducing and robustly testing the bulldozer db system
b) reworking the payments underlying architecture to use bulldozer for
correctness and scalability
c) Achieving parity with the old payments system excepting a few changes
like ensuring correctness of the ledger algo
There may still be some work to do with handling refunds, decoupling the
concepts of purchases from that of products, and some other things.
### Ledger Algorithm
This has been tuned and fixed. Item removals i.e negative item quantity
changes will apply to the soonest expiring item grant i.e positive item
quantity change. This is what is best for the user. Item grants can also
expire, and when they expire we obviate whatever is left of their
original capacity (meaning after all the removals that were applied to
it). Our ledger algo is applied via Bulldozer, so automatic
re-computation is handled when a new grant/ removal is inserted in the
middle of the existing ones.
### Things we got rid of
* No more automatic support for default products. You can use $0 plan
provisions to accomplish the same effect but it's manual
* Negative item quantity changes (i.e item removals) no longer can have
expiries
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Enhanced payment processing pipeline with improved data consistency
and state management.
* Advanced refund handling with comprehensive transaction tracking.
* Better tracking and management of customer item quantities and owned
products.
* Improved subscription lifecycle management including period-end
handling.
* **Bug Fixes**
* Fixed payment data integrity verification.
* Improved handling of edge cases in refund scenarios.
* **Chores**
* Updated cSpell configuration with additional words.
* Expanded developer documentation for linting workflows.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
Co-authored-by: Aadesh Kheria <kheriaaadesh@gmail.com>
Co-authored-by: Mantra <87142457+mantrakp04@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **New Features**
* Added Stripe, OAuth, and Freestyle mock services to the local emulator
* Introduced `emulator run` CLI command to execute applications with
emulator credentials automatically injected
* Enhanced credential management for local development
* **Improvements**
* Improved ARM64 QEMU emulation with cross-architecture support
* Better error detection and logging during emulator provisioning
* Added example middleware configuration with authentication support
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Owned admin apps are constructed with `tokenStore: null`, which caused
EventTracker/SessionRecorder flushes to throw from
_ensurePersistentTokenStore() after #1331 removed the silencing.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved analytics stability and privacy by restricting session
recording and event tracking to environments with required persistent
storage.
* **Tests**
* Adjusted a few end-to-end tests to skip when running against a local
emulator to reduce spurious failures.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- Extended `CliAuthAttempt` with `anonRefreshToken` and a migration.
- CLI `POST /auth/cli` accepts optional `anon_refresh_token` (must be an
anonymous user's refresh token for the current project).
- `POST /auth/cli/complete` supports `mode` `check` (anonymous vs none),
`claim-anon-session` (issue tokens for the linked anonymous session),
and `complete` (bind the browser session's refresh token to the
attempt). Completing clears `anonRefreshToken` on the row. We do **not**
merge anonymous account data into the signed-in user (that behavior was
removed as a security risk; the anonymous user remains unchanged).
- Template CLI confirmation page, stack-cli optional
`STACK_CLI_ANON_REFRESH_TOKEN`, SDK/spec updates, and e2e coverage.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* CLI login supports attaching anonymous sessions and a multi-mode
confirm/claim/check flow; CLI tools now surface login codes and remove
anon token after use.
* Added interactive CLI auth demo page and a CLI simulator script.
* Client libraries: prompt flow accepts an optional anon token and a
promptLink(url, loginCode) callback.
* **Tests**
* Expanded end-to-end coverage for anonymous CLI sessions,
claim/complete/poll flows, upgrades, and error cases.
* **Documentation**
* Updated prompt CLI docs/spec to describe new options and callback
signature.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The gate delayed flushes until an access token resolved, but sendBatch
already resolves the session itself via _getSession() at send time, so
_lastKnownAccessToken was a redundant readiness check that caused
head-of-session events to be silently dropped on slow auth init and
suppressed uploads entirely when token fetch failed.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Simplified analytics, session-replay, and event-tracking to stop
periodic background access-token refreshes; flushing now occurs based on
buffered data and lifecycle triggers.
* **Bug Fixes**
* Anonymous-user fallback tightened: anonymous identity is only applied
when explicitly requested as "anonymous-if-exists," preventing
unintended anonymous attribution.
* **Tests**
* Updated timing helper and removed token callback from test setups to
align with the new flush behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- Updated package versions for '@supabase/*' libraries to 2.99.2 and
'@supabase/ssr' to 0.9.0.
- Added new devDependencies for 'rimraf' and 'framer-motion' in the
pnpm-lock file.
- Modified Next.js configuration to conditionally omit 'X-Frame-Options'
in development mode for better integration with Stack Auth dev tools.
- Refactored component exports in the template package to include
tracking for dev tools.
- Introduced new dev tool components and context for improved logging
and state management.
- Added styles for the dev tool indicator and panel, ensuring a
consistent dark theme.
- Implemented fetch interception to log API calls and user
authentication events in the dev tool.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **New Features**
* Added comprehensive Developer Tools interface with tabs for Overview,
Components, AI Chat, Console, Dashboard, and Support.
* Integrated AI Chat assistant within Developer Tools for enhanced
debugging.
* Added component version tracking and update notifications.
* Implemented API request logging and event monitoring.
* Enhanced feedback system with support for bug reports and feature
requests.
* **Bug Fixes**
* Fixed Content Security Policy headers for local development
environments.
* **Dependencies**
* Added AI SDK integration packages.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
`window.screen` and `window.history` are accessor properties on
`Window.prototype`, so `Object.getOwnPropertyDescriptor(window,
X)?.value` returned undefined in real browsers, causing `start()` to
short-circuit and never capture or send any $page-view / $click events.
Read the globals directly instead; the jsdom-based regression test pins
the accessor-descriptor shape so this can't silently come back.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Tests**
* Added a new test suite verifying event batching, timing, page-view and
click event capture, and client-side navigation behavior using simulated
timers and DOM environment.
* **Bug Fixes**
* Improved event tracker reliability by changing how browser screen and
history are read, yielding more consistent detection of screen
dimensions and navigation for analytics capture.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- Added support for `@opentelemetry/sdk-node` in the backend.
- Updated various dependencies including AWS SDK and OpenTelemetry
packages.
- Implemented graceful shutdown handling for non-Vercel runtimes in
`prisma-client.tsx`.
- Enhanced AWS credentials retrieval to support GCP Workload Identity
Federation.
- Introduced a Dockerfile for Cloud Run deployment, optimizing the
backend build process.
- Updated `.gitignore` to include Terraform runtime files and secrets.
This commit improves the backend's observability and deployment
flexibility, particularly for Cloud Run environments.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* OpenTelemetry observability with dynamic provider selection per
deployment.
* Cloud Run trusted-proxy support for accurate client IP handling.
* Graceful shutdown that waits for in-flight background work.
* New background-task handling to improve async webhook/email delivery
reliability.
* AWS credential providers added (Vercel OIDC & GCP Workload Identity
Federation).
* Dockerized backend image for Cloud Run / self-host deployments.
* **Chores**
* Updated dependencies for OpenTelemetry and AWS SDK support.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
