Merge branch 'dev' into docs/apps_updates

Author: madster456

.claude/CLAUDE-KNOWLEDGE.md

@@ -2,6 +2,9 @@
 
 This file contains knowledge learned while working on the codebase in Q&A format.
 
+## Q: Which Hexclave rename compatibility layers should be avoided in PR #1475 follow-ups?
+A: Do not keep backwards compatibility for the MCP tool name, cross-domain auth query parameter names, `NEXT_PUBLIC_STACK_PORT_PREFIX`, or a parallel `hexclaveAppInternalsSymbol`. For refresh/access cookies, read both legacy Stack and new Hexclave cookie names, but only write the canonical Hexclave cookies.
+
 ## Q: How should GitHub Contents API request-body assertions be written in Stack Auth tests?
 A: Prefer inline snapshots over individual field selectors. For request bodies that contain base64 file content, parse the JSON body, assert it is an object, decode the `content` field back to UTF-8, and snapshot the normalized call object so the test verifies the path, method, headers, branch, message, sha, and rendered file content together.
 
@@ -535,3 +538,18 @@ A: The workflow needs a full checkout using the fine-grained `NPM_PUBLISH_VERSIO
 
 ## Q: How should the Mintlify docs homepage reuse the generated setup prompt?
 A: Import `generatedSetupPromptText` from `docs-mintlify/snippets/home-prompt-island.jsx` in `docs-mintlify/index.mdx`, render it directly in a `<pre><code>{generatedSetupPromptText}</code></pre>` block, and keep the home copy button wired to that imported value. Clipboard failures can happen when the browser document is not focused, so the button should surface the actual error text instead of only saying "Copy failed".
+
+## Q: Where should Mintlify docs for restricted users live?
+A: Put restricted-user docs at `docs-mintlify/guides/apps/authentication/restricted-users.mdx` and register the page in the Authentication group in `docs-mintlify/docs.json`. The page should cover `includeRestricted: true`, `user.isRestricted`, `user.restrictedReason`, anonymous users being restricted by definition, and JWKS `include_restricted=true` for services that intentionally accept restricted-user tokens.
+
+## Q: How should e2e tests switch to a newly created project?
+A: `Project.createAndSwitch` should leave `backendContext.projectKeys` set to real project API keys, not only `{ projectId, adminAccessToken }`. Internal admin access tokens are regular short-lived access tokens; keeping one in the default project context makes later server/admin requests fail with `ADMIN_ACCESS_TOKEN_EXPIRED` or validate the token against the wrong project.
+
+## Q: How should backend SMTP SSRF checks be rolled out?
+A: Keep the real outbound SMTP policy in `apps/backend/src/private/implementation/smtp-egress-policy.ts`, export it through `apps/backend/src/private/index.ts`, and provide a simple `implementation-fallback` function for self-hosters. It should allow only SMTP ports 25, 465, 587, 2465, 2587, and 2525, reject internal IP literals or DNS resolutions, and initially run report-only from `emails-low-level.tsx` via `captureError("smtp-egress-policy-report-only", ...)` before enforcing hard failures.
+
+## Q: What project-level `sourceOfTruth` config is supported?
+A: Project config overrides only support the hosted `sourceOfTruth` shape. Legacy external source-of-truth overrides such as Postgres or Neon are removed by `migrateConfigOverride("project", ...)`, while raw schema validation should reject them.
+
+## Q: How should managed email onboarding e2e tests wait for mock verification?
+A: Do not rely on a fixed `wait(1500)` after setup. The mock onboarding path flips the domain to `verified` asynchronously through `runAsynchronously`, so tests should poll the managed-onboarding check endpoint until the expected status appears.

.github/workflows/e2e-custom-base-port-api-tests.yaml

@@ -18,7 +18,7 @@ jobs:
       NODE_ENV: test
       STACK_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING: yes
       STACK_DATABASE_CONNECTION_STRING: "postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:6728/stackframe"
-      NEXT_PUBLIC_STACK_PORT_PREFIX: "67"
+      NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX: "67"
       STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
       STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
 

.github/workflows/qemu-emulator-build.yaml

@@ -148,10 +148,12 @@ jobs:
       - name: Build stack-cli (for emulator CLI)
         if: matrix.arch == 'amd64'
         run: |
-          pnpm install --frozen-lockfile --filter '@stackframe/stack-cli...'
-          # Turbo's trailing `...` filter builds stack-cli AND its workspace
-          # deps (@stackframe/js, @stackframe/stack-shared, etc.) — stack-cli
-          # imports them at runtime from their dist/ outputs.
+          # Turbo's task graph for stack-cli#build includes
+          # @stackframe/dashboard#build:rde-standalone, which transitively
+          # depends on @stackframe/stack#build (via dashboard → stack).
+          # The pnpm filter must cover the dashboard dep tree too so that
+          # devDependencies like tailwindcss are installed for the build.
+          pnpm install --frozen-lockfile --filter '@stackframe/stack-cli...' --filter '@stackframe/dashboard...'
           pnpm exec turbo run build --filter='@stackframe/stack-cli...'
 
       - name: Start emulator and verify
@@ -267,10 +269,8 @@ jobs:
 
       - name: Install stack-cli deps + build
         run: |
-          pnpm install --frozen-lockfile --filter '@stackframe/stack-cli...'
-          # Turbo's trailing `...` filter builds stack-cli AND its workspace
-          # deps (@stackframe/js, @stackframe/stack-shared, etc.) — stack-cli
-          # imports them at runtime from their dist/ outputs.
+          # See "Build stack-cli" step comment for why dashboard filter is needed
+          pnpm install --frozen-lockfile --filter '@stackframe/stack-cli...' --filter '@stackframe/dashboard...'
           pnpm exec turbo run build --filter='@stackframe/stack-cli...'
 
       - name: Download built image

.github/workflows/setup-tests-with-custom-base-port.yaml

@@ -19,17 +19,17 @@ jobs:
     if: ${{ (github.head_ref || github.ref_name) == 'dev' }}
     runs-on: ubicloud-standard-16
     env:
-      NEXT_PUBLIC_STACK_PORT_PREFIX: "69"
+      NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX: "69"
       STACK_EXTERNAL_DB_SYNC_MAX_DURATION_MS: "20000"
       STACK_EXTERNAL_DB_SYNC_DIRECT: "false"
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
-      - name: Setup Node.js v20
+      - name: Setup Node.js v22
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Setup pnpm
         uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4

.github/workflows/setup-tests.yaml

@@ -24,10 +24,10 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 
-      - name: Setup Node.js v20
+      - name: Setup Node.js v22
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Setup pnpm
         uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4

.vscode/settings.json

@@ -121,9 +121,11 @@
     "xact",
     "zustand"
   ],
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit",
-    "source.organizeImports": "explicit"    
+  "[typescript]": {
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit",
+      "source.organizeImports": "explicit"    
+    },
   },
   "terminal.integrated.wordSeparators": " (){}',\"`─‘’“”|",
   "editor.formatOnSave": false,

AGENTS.md

@@ -116,6 +116,8 @@ To see all development ports, refer to the index.html of `apps/dev-launchpad/pub
 - NEVER INSTALL A NEW PACKAGE (or anything else) WITHOUT EXPLICIT APPROVAL FROM THE USER.
 - A "development environment" is either an RDE (remote development environment; = local dashboard + prod backend) or a local emulator (local dashboard + local backend). When communicating to the user, we always say "development environment" instead of RDE or local emulator (the distinction to the user is minor, even though the implementation is quite different).
 - NEVER EVER return a server error with an internal server error that may contain information that the user shouldn't see. For example, never return the error message on a public API from an upstream provider without properly filtering it first. Most of the time, for internal server errors, you should just use StackAssertionError (which won't pass the message to the user), not StatusError (you almost never want to instantiate a StatusError with status 5xx).
+- When adding code to the `private` part of the backend, put the actual implementation into `implementation` (if the submodule is checked out), and implement a simple fallback in `implementation-fallback` for self-hosters. `implementation.generated.ts` will automatically be generated, which you can then import from `index.ts`. (See the existing code as an example.) If the submodule isn't checked out, but you need to add code to the `private` part of the backend, let the user know.
+- Security-sensitive code on the backend that shouldn't be public should be in the `private` part of the backend.
 
 ### Code-related
 - Use ES6 maps instead of records wherever you can.

CHANGELOG.md

@@ -2,37 +2,52 @@
 
 ---
 
-## 1/23/26
+## 5/22/26
 
-### Payments
-Introduced a redesigned payments onboarding flow
-![Payments Onboarding](https://raw.githubusercontent.com/stack-auth/stack-auth/dev/apps/dashboard/public/changelog/payments-onboarding.png)
+- Faster ClickHouse analytics for project metrics and previews.
+- Smoother cross-domain auth handoffs and hosted-domain trust.
+- Sharper Auth Methods and Users dashboard tables.
+![Auth method and user table polish](https://raw.githubusercontent.com/hexclave/stack-auth/dev/apps/dashboard/public/assets/changelog-auth-methods.png)
 
-## 1/21/26
+## 5/15/26
 
-### Payments
-- Payments page updated with new UI changes
-![Create Product](https://raw.githubusercontent.com/stack-auth/stack-auth/refs/heads/dev/apps/dashboard/public/changelog/payments-create-product.png)
-- Added a new Payments Settings page with an option to temporarily disable all payments
-![Payments Setting](https://raw.githubusercontent.com/stack-auth/stack-auth/refs/heads/dev/apps/dashboard/public/changelog/payments-settings-1.png)
-- Subscription renewal emails are now sent automatically to users
-- Past payment invoices are now visible on the Account Settings page
-![Past Payments Invoices](https://raw.githubusercontent.com/stack-auth/stack-auth/refs/heads/dev/apps/dashboard/public/changelog/account-settings-invoices.png)
+- Redesigned Team Management tables with cleaner action states.
+- New project transfer, session replay, and team payments screens.
+- Unified AI chat experience on assistant-ui threads.
+![Team management table](https://raw.githubusercontent.com/hexclave/stack-auth/dev/apps/dashboard/public/assets/changelog-teams.png)
 
-### Documentation
-- Updated JWT documentation to include `isRestricted` and `restrictedReason`
+## 5/8/26
 
-## 1/19/26
-- Updated package dependencies to their newest versions.
+- New TanStack Start SDK integration with refreshed OpenAPI schemas.
+- Weekly active users now appear on Project Overview.
+- Cleaner Project Permissions with upgraded data grids.
+![Project permissions dashboard](https://raw.githubusercontent.com/hexclave/stack-auth/dev/apps/dashboard/public/assets/changelog-rbac.png)
 
-## 12/19/25
-- Introduces new changelog and deprecates all older changelogs. 
-- Date versioning for public view.
+## 5/1/26
+
+- Shareable Session Replay IDs across dashboard, backend, and SDKs.
+- Sleeker Data Vault and overview data-grid layouts.
+- Emulator updates can now auto-install dependencies.
+![Data Vault dashboard](https://raw.githubusercontent.com/hexclave/stack-auth/dev/apps/dashboard/public/assets/changelog-data-vault.png)
+
+## 4/24/26
+
+- Redesigned Email Server settings and managed-domain setup.
+- Faster local emulator startup with RAM snapshots.
+- Live secret rotation plus a simpler sign-up rules tester.
+![Email server settings and logs](https://raw.githubusercontent.com/hexclave/stack-auth/dev/apps/dashboard/public/assets/changelog-email-server.png)
+
+## 4/17/26
+
+- Redesigned Overview and onboarding experience.
+- Crisper dashboard sidebar styling and category navigation.
+- New Payments product setup flow.
+![Payments product setup](https://raw.githubusercontent.com/hexclave/stack-auth/dev/apps/dashboard/public/assets/changelog-payments-products.png)
 
 ---
 
-> **Note:** All older changelogs are deprecated and have been removed. The source of true is this single changelog file.
-> 
+> **Note:** All older changelogs are deprecated and have been removed. The source of truth is this single changelog file.
+>
 > Going forward, all changes should be documented in this file only.
 
 ---