## What
Continues the **Stack Auth → Hexclave** rename for a set of safe,
internal-only surfaces. This intentionally avoids public-contract names.
### Changes
- **Examples** — renamed the user-facing config module
`stack.ts`/`stack.tsx` (and the `convex` / `lovable` `stack/`
directories) to `hexclave`, and updated every importer across
`.ts`/`.tsx`/`.jsx`. The public `app/handler/[...stack]/` route segment
is left unchanged.
- **apps/{dashboard,backend,internal-tool}** — renamed app-local
SDK-init symbols `stackClientApp → hexclaveClientApp` and
`getStackServerApp → getHexclaveServerApp`, and the dashboard
`StackCompanion` component → `HexclaveCompanion` (incl.
`useStackCompanion`, context types). The public
`StackClientApp`/`StackServerApp` SDK classes are **unchanged**.
- **packages/stack-shared** — added comments to the crypto / JWT / vault
`stack-*` literals documenting that they must **not** be renamed (key
derivation / JWKS / KMS-alias stability). The literals are
byte-identical.
### Deliberately excluded
- **`STACK_*` → `HEXCLAVE_*` env-var rename** — `HEXCLAVE_*` already
resolves via the dual-read layers (SDK env, dashboard `_inlineEnvVars`,
`getEnvVariable`). The remaining holdout is the docker post-build
sentinel path, which the codebase authors explicitly deferred and which
is tightly coupled to `entrypoint.sh` + untestable here. A blind rename
there risks silently breaking self-host/emulator bootstrap for ~zero
functional gain.
- **All public-contract names** — SDK class names, env vars, HTTP
headers (`x-stack-*`), and the `/handler` route convention.
## Verification
- `pnpm lint` — **29/29 passing**.
- `pnpm typecheck` — **28/29 passing**; the only failure is
`@hexclave/docs` (pre-existing missing fumadocs `.source` codegen,
untouched by this PR).
- Two rounds of adversarial multi-agent review; findings fixed:
string-literal collateral from the symbol sweep (CLI test fixtures + an
AI-prompt template) reverted, and a missed `.jsx` importer in
`examples/cjs-test` corrected.
## Notes
- Based on a `dev` snapshot from when the branch was cut (a couple
commits behind tip); the diff contains only the changes above.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Complete the internal “Stack” → “Hexclave” rename across examples,
app-local code, config tooling, and setup docs, and standardize env
output to HEXCLAVE_* with correct default API URL handling. Public SDK
classes, handler routes, and legacy env names keep working.
- **Refactors**
- Examples/config: `stack.*` files and `stack/` dirs →
`hexclave.*`/`hexclave/`; imports updated; keep `app/handler/[...stack]`
route.
- Apps: backend/dashboard/internal-tool now use `getHexclaveServerApp`
and `hexclaveClientApp`; dashboard `StackCompanion` →
`HexclaveCompanion`. Public `StackClientApp`/`StackServerApp` unchanged.
- Env/setup: Next.js and CLI generators write HEXCLAVE_* and omit API
URL when using https://api.stack-auth.com; CLI `doctor` and auth
resolution prefer HEXCLAVE_* (e.g. `HEXCLAVE_SECRET_SERVER_KEY`,
`HEXCLAVE_PROJECT_ID`) with `STACK_*` fallback.
- Config tooling: `stack-config-file` → `hexclave-config-file`, emitting
`HexclaveConfig`; imports updated across backend/dashboard/tooling.
- Shared/docs: added “do not rename” notes for crypto/JWT/vault
`stack-*` literals; regenerated setup prompt/docs to use
`hexclave.config.ts`, `hexclave dev`, and `src/hexclave/`.
- Tests: updated snapshots/assertions to expect `HexclaveConfig` and
HEXCLAVE_* env names.
- **Migration**
- No action required. SDK and CLI read both HEXCLAVE_* and STACK_*.
<sup>Written for commit 8a891b4f6c.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1534?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Renamed internal app/client/server instances and companion/provider
components to the new product name across backend, dashboard, examples,
and tooling; imports updated accordingly.
* Updated generated environment variable names and CLI init/doctor
outputs to prefer the new product prefix.
* **Documentation**
* Added clarifying notes about vault/encryption and JWT/key labels to
avoid breaking existing encrypted data.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Four Mintlify doc pages threw runtime console errors and rendered
broken/empty content. Two distinct root causes:
1. **`HexclaveAgentReminders` snippet** — broke Setup, "Using Hexclave
with AI", and Stack CLI pages (and home). The component referenced a
sibling module-level export (`<pre>{hexclaveReminders}</pre>`), but
Mintlify evaluates an imported snippet component in an isolated scope
that does not include sibling exports, throwing `hexclaveReminders is
not defined`. Fixed by inlining the value into the component (matching
the self-contained pattern of every other working snippet). The snippet
is generated, so the generator `scripts/generate-setup-prompt-docs.ts`
was updated too.
2. **`connected-account.mdx`** — SDK ConnectedAccount page rendered
empty because it used `CollapsibleTypesSection`/`MethodLayout`/etc. but
was missing the `/snippets/sdk-type-components.jsx` import that all
other SDK type pages have (`Expected component CollapsibleTypesSection
to be defined`). Added the import.
## Validation
- All 4 pages render fully with clean browser consoles (verified locally
via the `mint` dev server).
- `mint validate` passes.
- Re-running the generator produces no diff (snippet stays in sync with
the generator).
Link to Devin session:
https://app.devin.ai/sessions/6ef551840f104808937c325d3f105e7a
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes console errors and empty renders in Mintlify Hexclave docs by
making the `HexclaveAgentReminders` snippet self-contained and adding
missing SDK type component imports in `connected-account.mdx`. Also
removes an unused export to avoid duplication.
- **Bug Fixes**
- Inlined content in `HexclaveAgentReminders` and updated
`scripts/generate-setup-prompt-docs.ts` to emit it, resolving
ReferenceError on Setup, Using Hexclave with AI, Stack CLI, and home
pages.
- Added missing `/snippets/sdk-type-components.jsx` import and the
`ContentSection`/`MethodReturns` named imports in
`sdk/types/connected-account.mdx` so type components render.
- **Refactors**
- Removed the unused `hexclaveReminders` export from the snippet.
<sup>Written for commit b5f2f7a28e.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1541?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: aman <aman@stack-auth.com>
## Summary
Three related fixes, surfaced while investigating a production error on
managed email onboarding.
### 1. DNSimple managed-email zone deletion (the reported production
error)
`deleteDnsimpleZoneByName` issued `DELETE /v2/{account}/zones/{zone}`,
but **DNSimple's v2 API has no DELETE endpoint for zones**. Zones are
created here by creating a *domain* (`POST /domains`), so the symmetric
teardown is `DELETE /domains/{name}`, which also removes the hosted
zone. The old call returned a non-OK status, throwing:
> `HexclaveAssertionError: DNSimple returned non-OK status when deleting
managed email zone`
on every managed-domain deletion (the Resend domain was already deleted
by then, so the request 500s and the DNSimple zone leaks). Now deletes
the owning domain.
### 2. `applyManagedEmailProvider` left configs in an invalid state
The apply early-returned on `domain.status === "applied"` **without
rewriting config**. If the config had since drifted (e.g. the user
switched to a shared/other provider and back), re-applying never
restored `password`/`senderName`, so the *rendered* config was invalid
and **every `GET /internal/projects` 500'd** with `Result admin
validation failed in CRUD handler` (dashboard then loops/refreshes). Now
it only short-circuits when the config actually uses the domain
(`isManagedEmailDomainInUseForTenancy`); otherwise it re-provisions and
writes the full valid config.
### 3. Email-settings dashboard: managed domain now uses the staged save
flow
Clicking "Use this domain" fired an immediate API call and only
refreshed the domains *list* — never the project config the UI derives
"active" from — so nothing visibly changed and it appeared not to
persist. Applying a managed domain now matches the other providers:
selecting a domain stages a draft and shows the standard **"Unsaved
changes → Save"** card; **Save** calls `applyManagedEmailProvider`
(which owns the full config write) and then refreshes the reactive
config cache so the UI flips to **Active**.
### 4. Build unblock: `@stackframe/stack-shared` → `@hexclave/shared`
The `@hexclave/*` rename (#1482) missed `createGlobal`'s import in two
template providers, and PR 3 deleted the compat alias — so `pnpm
build:packages` couldn't resolve
`@stackframe/stack-shared/dist/utils/globals` when building the
dashboard. Fixed in the template (generated SDKs follow). *(Independent
of the email fixes, but required to build the branch.)*
## Files
- `apps/backend/src/lib/managed-email-onboarding.tsx` — DNSimple domain
delete + apply re-provision-on-drift
- `apps/dashboard/.../email-settings/domain-settings.tsx` — staged
managed-domain apply
-
`packages/template/src/providers/{stack-context,translation-provider-client}.tsx`
— globals import rename
## Testing
- `tsc --noEmit` and `eslint` clean on `@hexclave/backend` and
`@hexclave/dashboard`.
- `pnpm build:packages` + `pnpm codegen` succeed; dashboard
email-settings route compiles and serves `200`.
- Reproduced the 500 loop locally, root-caused it to a partial managed
config override, and reset the affected project's `emails.server`
override to recover.
## Notes
- Applying a managed domain still calls the API once (to mint the scoped
Resend sending key) — that call now happens on **Save** rather than on
click.
- The older `apps/dashboard/.../emails/page-client.tsx` has the same
immediate-apply pattern; left untouched pending confirmation that screen
is still in use.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes managed email onboarding: deletes DNSimple domains correctly,
restores a valid managed config on re-apply, and moves managed-domain
apply to a staged Save that waits for the domain list and shows
selection state. Also updates imports to `@hexclave/shared` to unblock
builds.
- **Bug Fixes**
- DNSimple teardown: use DELETE `/domains/{name}` (zones have no
DELETE). Stops errors and zone leaks when removing managed domains.
- `applyManagedEmailProvider`: only short-circuits when the rendered
config already uses the domain; otherwise re-provisions and writes the
full managed config to prevent invalid renders and 500s.
- Dashboard: managed domain selection now stages a draft; Save calls
`applyManagedEmailProvider`, refreshes the config cache, and the UI
updates. Shows “Selected — save to apply,” supports deselecting,
requires a selection, and disables Save until the domains list finishes
loading.
- **Dependencies**
- Renamed globals import from `@stackframe/stack-shared` to
`@hexclave/shared` to restore `pnpm build:packages`.
<sup>Written for commit 6ecb6a1ff8.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1527?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved detection and recovery for managed email configuration drift
scenarios
* Fixed teardown behavior to avoid leaving inconsistent managed domain
state
* **New Features**
* Managed domain selection now requires explicit save confirmation
before applying
* Added status labels showing current vs staged domain and pending
changes
* Added ability to deselect staged managed domains; deleting a domain
clears any draft
* Save now shows applied sender identity via toast after applying
managed domain
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/hexclave/hexclave/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Improve ClickHouse readiness check for local startup and make it
non-blocking with clearer logs. Also tighten workspace build
permissions.
- **Bug Fixes**
- Updated `wait-until-clickhouse-is-ready` to log status, use `wait-on`
with `http-get://`, verbose output, and a 10s timeout; continue with a
warning if ClickHouse isn’t ready.
- **Dependencies**
- Set `@quetzallabs/i18n` to `false` in `pnpm-workspace.yaml`
`allowBuilds` to prevent building that package.
<sup>Written for commit f24cf668b9.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1535?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Improved dependency readiness checks with enhanced error handling and
logging during system initialization.
* Updated build configuration to optimize package dependency management
and build processes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
Fixes the 9 failing tests in the E2E (Local Emulator) job — 2 test
files, both stale after recent refactors that renamed source but missed
the tests.
### `apps/e2e/tests/general/cli.test.ts` (6 failures)
The `stack emulator` command was removed in #1522 (which also reworded
its auth errors from "local emulator" → "development environment"), but
the e2e tests were never updated:
- Updated two error-string assertions:
- `"Local emulator publishable client key not found"` → `"Development
environment publishable client key not found"`
- `"Cannot reach local emulator"` → `"Cannot reach development
environment"`
- Removed the dead `"Stack CLI — Emulator"` describe block (4 tests for
the deleted `emulator pull/start/stop/list-releases` subcommands) and
the now-unused `CLI_SRC_BIN` const.
###
`apps/dashboard/src/lib/remote-development-environment/config-file.test.ts`
(3 failures)
Leftover `@stackframe/*` names from the `@hexclave` rename:
- Fixture imports `@stackframe/stack-shared/config` →
`@hexclave/shared/config` (the `defineStackConfig` /
`defineHexclaveConfig` cases were failing with `Cannot find module`).
- Rendered-config snapshot type import `@stackframe/js` →
`@hexclave/js`.
## Verification
- `config-file.test.ts`: **7 passed**.
- `cli.test.ts` against a live local backend: **69 passed / 4 skipped /
0 failed** (the 4 skips are environment-gated `it.runIf`/`it.skip`, not
failures).
- Reproduced both CLI error paths against the built CLI binary to
confirm the new strings match exactly.
- `lint` ✓ and `typecheck` ✓ for `@hexclave/e2e-tests` and
`@hexclave/dashboard`.
Only test files are changed — no production code.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes 9 failing E2E tests by updating CLI error messages and RDE config
test imports after the emulator command removal and the `@hexclave`
rename. Removes obsolete emulator CLI tests; no production code changed.
- **Bug Fixes**
- CLI: updated two error-string assertions to use “Development
environment …” wording.
- CLI: removed the obsolete “Stack CLI — Emulator” test block and the
unused `CLI_SRC_BIN`.
- Dashboard RDE config tests: replaced `@stackframe/stack-shared/config`
with `@hexclave/shared/config`.
- Snapshot import: `@stackframe/js` → `@hexclave/js`.
<sup>Written for commit a887d7209b.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/stack-auth/pull/1528?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Updated error messages to use "development environment" terminology
instead of "emulator" references.
* **Tests**
* Adjusted test assertions and imports for consistency with updated
terminology.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Why the build fails on `origin/dev`
The `Lint & build` workflow fails at the **Build** step, in
`@hexclave/lovable-react-18-example`'s `vite build`:
```
[vite]: Rollup failed to resolve import "@stackframe/stack-shared/dist/utils/globals"
from ".../packages/react/dist/esm/providers/stack-context.js".
```
(failing run: [job
78596906597](https://github.com/hexclave/stack-auth/actions/runs/26665187298/job/78596906597))
### Root cause
PR 3 (`feat(hexclave): PR 3 — native @hexclave/* source rename + delete
dual-publish wiring`, #1482) renamed `@stackframe/stack-shared` →
`@hexclave/shared` and **deleted the dual-publish wiring**, so
`@stackframe/stack-shared` is no longer a resolvable package.
Two `packages/template/src` provider files were missed in that rename:
- `packages/template/src/providers/stack-context.tsx`
- `packages/template/src/providers/translation-provider-client.tsx`
`packages/react` ships only `package.json`; its `src`/`dist` are
**generated** from `packages/template/src` by `generate-sdks`, which
copies import specifiers verbatim. So the stale
`@stackframe/stack-shared` import propagated into `packages/react/dist`.
The `@hexclave/react` build itself **succeeds** because tsdown/rolldown
externalizes the import (it never has to resolve it). The failure only
surfaces downstream, when `lovable-react-18-example` bundles
`@hexclave/react` with Vite/Rollup and tries to actually resolve
`@stackframe/stack-shared` — a package that no longer exists.
## Fix
Point both imports at the renamed package, matching the convention
already used by sibling files (e.g. `stack-provider-client.tsx`,
`common.ts`):
```diff
-import { createGlobal } from "@stackframe/stack-shared/dist/utils/globals";
+import { createGlobal } from "@hexclave/shared/dist/utils/globals";
```
## Verification
Reproduced and confirmed the fix locally:
1. Edited the two template files.
2. `pnpm -w run generate-sdks` → generated `packages/react/src` now
imports `@hexclave/shared/dist/utils/globals`.
3. `pnpm --filter @hexclave/react run build` →
`dist/esm/providers/stack-context.js` now imports `@hexclave/shared` ✔
4. `pnpm --filter @hexclave/lovable-react-18-example run build` → **`✓
built`** (previously failed at this exact step).
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Rename leftover imports from `@stackframe/stack-shared` to
`@hexclave/shared` in the template providers to fix downstream build
failures. This unblocks Vite/Rollup consumers (e.g.,
`@hexclave/lovable-react-18-example`) by resolving `createGlobal` from
the correct package.
<sup>Written for commit 15901edb2b.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/stack-auth/pull/1525?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated internal module dependencies across provider configurations.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1525?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
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
Replaces the request-host-header-derived OAuth `redirect_uri` with a
config-driven `customCallbackUrl` field on each environment-level OAuth
provider.
Resolution of the `redirect_uri` we send to providers (and that
customers register in their provider app config):
- **Shared providers** → always the stack-auth-branded callback, so
Stack's shared OAuth apps keep working. `customCallbackUrl` is
schema-forbidden when `isShared` is true.
- **Custom + `customCallbackUrl` set** → the configured URL verbatim.
- **Custom without it (legacy)** → the stack-auth-branded callback, so
providers registered before this field are unaffected.
- **New custom providers set up in the dashboard** → the env-aware
hexclave-branded callback (prod → `api.hexclave.com`, dev/staging →
siblings, self-host/localhost → `NEXT_PUBLIC_STACK_API_URL` unchanged).
## Details
- **Schema** (`schema.ts`, `schema-fields.ts`): optional
`customCallbackUrl` after `clientSecret`, with a `.when('isShared')`
rule rejecting any value for shared providers; added to the provider
default factory.
- **Shared host helper** (`utils/cloud-hosts.tsx`, new):
`CLOUD_HOST_PAIRS` moved into stack-shared with `getCloudApiUrlSiblings`
/ `getStackAuthApiBaseUrl` / `getHexclaveApiBaseUrl`;
`request-api-url.ts` re-exports it so the JWT `iss` logic is untouched.
- **Runtime** (`oauth/index.tsx` + all 13 provider `create()`s):
`getProvider` resolves the full `redirect_uri` from config instead of
the request host; providers now take `redirectUri` instead of `apiUrl`.
The JWT `iss` path still uses the request host.
- **Dashboard** (`page-client.tsx`, `providers.tsx`,
`oauth-callback-url.ts` new): brand-new custom providers get the
hexclave callback; existing providers keep whatever they had (edits
never silently move a registered redirect URL); the displayed Redirect
URL mirrors backend resolution.
- **Docs** (`migration.mdx`): existing `api.stack-auth.com` callbacks
keep working; only recreated providers use the hexclave URL.
## Notes / scope decisions
- **Dashboard-only injection**: SDK/CLI/legacy-config-created custom
providers fall back to the stack-auth callback (they don't auto-get the
hexclave URL).
- **shared → standard** conversions keep the stack-auth fallback rather
than flipping to hexclave (the safe path that never breaks a registered
redirect).
## Test plan
- [x] `typecheck` + `lint` green across stack-shared, backend,
dashboard, e2e
- [x] cloud-hosts unit tests, schema tests, schema fuzzer pass
- [x] e2e: shared-provider `customCallbackUrl` rejected (400);
standard-provider `customCallbackUrl` accepted and round-trips
- [ ] e2e OAuth authorize/callback flow (needs running stack) — reasoned
unaffected since localhost isn't a cloud host, so the redirect base
stays localhost as before
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a per-provider `customCallbackUrl` for OAuth `redirect_uri`,
removing the request-host dependency and making redirects predictable.
Shared providers always use the Stack-branded callback; new or converted
custom providers default to the Hexclave-branded callback. Existing
callbacks keep working; no changes needed unless you recreate or convert
a provider.
- **New Features**
- Added `customCallbackUrl` on provider configs (URL-validated;
forbidden when `isShared` is true).
- `getProvider` now resolves a config-driven `redirectUri`; providers
take `redirectUri` instead of `apiUrl` (pure resolver with in-source +
e2e tests to lock legacy behavior).
- Introduced `@stackframe/stack-shared` `utils/cloud-hosts.tsx` and
dashboard helpers to show the resolved Redirect URL and set the Hexclave
callback for new providers and when converting shared → standard.
- **Bug Fixes**
- OAuth callback now handles legitimate cross-host flows by recording
the authorize host and skipping the host-scoped CSRF cookie when
authorize and callback hosts differ, relying on server-side state and
PKCE.
<sup>Written for commit 32d95fcdcb.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/stack-auth/pull/1512?utm_source=github">Review
in cubic</a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Preserve and display custom OAuth callback/redirect URLs in the
dashboard; provider creation/edit flows respect existing custom URLs.
* Added cloud-host mapping and redirect-uri helpers to resolve branded
API callback bases.
* **Bug Fixes**
* Improved cross-host OAuth callback handling and CSRF validation for
reliable cross-host flows.
* **Tests**
* Added E2E and unit tests covering callback URL behavior and host
mapping.
* **Documentation**
* Updated migration guidance for callback URL changes and recreation
scenarios.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1512?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
The **Active Sessions** table in account settings showed locations like
`San%20Francisco` instead of `San Francisco`.
Vercel percent-encodes its geolocation headers (e.g.
`x-vercel-ip-city`), so a multi-word city arrives URL-encoded. The city
name was being stored verbatim, so the raw `%20` leaked into the UI.
The fix decodes the city name where the Vercel geo header is read, so
recorded sessions store the human-readable name. This also benefits any
other consumer of the location data. It falls back to the raw value if
it isn't valid percent-encoding, so a stray `%` can't break things.
## Test plan
- [ ] Unit tests (in-source, `apps/backend/src/lib/end-users.tsx`):
simulating Vercel headers with `x-vercel-ip-city: San%20Francisco` now
yields `cityName: "San Francisco"`; an invalid-encoding value (`100%
Real City`) passes through unchanged instead of throwing. All 8 tests in
the file pass.
- [ ] In a Vercel-deployed environment, sign in and open Account
Settings → Active Sessions; confirm the Location column shows a plain
city name (e.g. `San Francisco`) with no `%20`.
> Note: this can't be reproduced on localhost because there's no Vercel
proxy supplying geo headers (the location shows `Unknown`). The behavior
is covered by the unit tests, which feed the exact headers Vercel sends.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Corrected handling of city name data from hosting-provided location
headers so multi-word city names display correctly and invalid
percent-encoding no longer causes errors.
* **Tests**
* Added tests to verify URL-decoded city names from location headers and
to ensure malformed encodings are safely preserved.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1503?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/hexclave/hexclave/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added Hexclave-branded aliases for public Stack APIs and updated
deprecation guidance to point to `@hexclave/*` and the migration guide.
Deprecation tags now live on source declarations so they survive dts
bundling; behavior unchanged.
- **Refactors**
- Added `HexclaveHandler`, `HexclaveProvider`, `HexclaveTheme`,
`useHexclaveApp`, and `HexclaveConfig`/`defineHexclaveConfig`; kept
`Stack*` as deprecated aliases.
- Moved deprecation JSDoc to original declarations and adjusted
`template/src/index.ts` re-exports; default exports preserved for
back-compat.
<sup>Written for commit 0077c8a560.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/stack-auth/pull/1510?utm_source=github">Review
in cubic</a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Primary exports rebranded to Hexclave names (handlers, providers,
theme, config, hooks) with deprecated Stack aliases preserved for
compatibility.
* Provider/theme/handler exports standardized to named exports and a
single default export per component.
* **Documentation**
* Improved deprecation guidance: legacy Stack symbols now carry
deprecation JSDoc pointing to Hexclave alternatives and migration docs.
* **Behavior**
* Hook useStackApp now delegates to the new useHexclaveApp; useUser
reads from the Hexclave-based hook.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1510?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
