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
- Use URLSearchParams with sorted keys for deterministic metrics cache key (cubic #21, vercel #45)
- Use refreshWhere(() => true) to invalidate all filtered cache entries on user refresh (cubic #53, coderabbit #32)
- Replace truthiness checks with explicit != null checks in filter serialization (coderabbit #26, cubic #55)
- Guard window.matchMedia with typeof check for JSDOM/test environments (vercel #44, #49)
- Use encodeURIComponent for projectId in analytics redirect URL (coderabbit #27)
Co-Authored-By: mantra <mantra@stack-auth.com>
- Introduced a new `containedHeight` prop in `PageLayout` to manage height behavior.
- Updated `SidebarLayout` and `PageClient` components to utilize `containedHeight` for improved layout control.
- Enhanced styling to ensure proper flex behavior based on the new prop, allowing for better content overflow management.
DesignPillToggle and DesignCategoryTabs called window.matchMedia and
new ResizeObserver unconditionally, which throws in environments without
those Web APIs (e.g. JSDOM tests, older browsers). Guard both before use;
the one-shot updateSliderMetrics still runs so layout stays correct. (CodeRabbit)
- Added `normalizeClickmapClicksQueryRows` function to standardize the processing of clickmap query results.
- Updated types to include raw data representations for routes, selectors, elements, users, and replays.
- Enhanced `runClickmapClicksQuery` to utilize the new normalization function, improving data handling and consistency.
- Introduced tests for the normalization function to ensure accurate scaling of sampled event counts while preserving unique user and replay counts.
## 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 -->
- Added new elements and functionality for clickmap list rows, including highlight and mute features.
- Implemented event handling for row interactions, allowing users to toggle muted states and highlight groups.
- Updated styles for improved visual feedback on muted and highlighted states in the clickmap overlay.
- Introduced a clear function for managing clickmap list elements, enhancing performance and usability.
- Introduced auto-copy feature for clickmap token snippets, improving user experience.
- Updated CopyField and CopyButton components to support initial copied state.
- Refactored PageClient to manage custom origin state and improve clickmap token handling.
- Added viewport warning styles and functionality to enhance user guidance in the dev tool.
- Cleaned up unused code and improved overall component structure for better maintainability.
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
- Added new API routes for clickmap data retrieval, including public and internal endpoints.
- Implemented token generation and validation for clickmap access, ensuring secure data handling.
- Refactored existing heatmap references to clickmap throughout the codebase for consistency.
- Enhanced error handling and validation for clickmap queries, improving robustness.
- Updated related components and tests to support the new clickmap features and ensure functionality.
- Updated all instances of "heatmap" to "clickmap" in the analytics module to reflect the new terminology.
- Adjusted console messages, alerts, and UI elements to align with the clickmap branding.
- Modified navigation items and dev-tool components to ensure cohesive user experience across the application.
- Consolidated heatmap query logic into shared utility functions for better maintainability.
- Updated heatmap overlay token handling to use consistent storage keys across components.
- Improved error handling for ClickHouse queries, ensuring proper status reporting.
- Added comprehensive tests for new query utilities and heatmap overlay functionality.
- Refactored related components to utilize the new utility functions, enhancing code clarity and reducing duplication.
- heatmap token verify: validate JWT audience and narrow the catch so
unexpected backend faults aren't misreported as auth failures
- heatmaps page: keep filter controls/grid mounted on fetch error
instead of replacing them with only an alert
- dev-tool: remove return from finally block (noUnsafeFinally)
- dev-tool: give the heatmaps tab a teardown lifecycle so leaving it
removes global blockers/observer/polling instead of caching the pane
- event-tracker: escape '.'/':' in class tokens of elements_chain and
decode them in the overlay parser so Tailwind variant classes round-trip
- SDK: expose camelCase options for getAnalyticsHeatmap and map to
snake_case in the impl (aligns with listSessionReplays)
- showHeatmap: handle token-creation failure (reset dialog) + call via
runAsynchronouslyWithAlert so errors surface (greptile P1, vercel, cubic)
- DEVICE_WIDTH_BUCKETS: use Map to avoid prototype-pollution lookup (greptile P2)
- dedup formatClickhouseDateTimeParam/parseBoundedDateTime across heatmap
routes by exporting from the internal route (greptile P2)
- derive heatmap JWT expiry from HEATMAP_TOKEN_TTL_MS (cubic)
- only report 'Invalid route regex' for actual ClickHouse regexp errors,
via shared isClickhouseRegexpError helper (cubic, both routes)
- generic top-elements error text instead of raw err.message (cubic)
- dev-tool: add primary-button :hover style to prevent hover flash (cubic)
- selector builder: emit the data-test-id attr name actually matched (cubic)
Merge codex/route-heatmaps into the analytics overview filters branch,
adding heatmap API routes, token signing, dashboard heatmap page, and
dev-tool/event-tracker support.
## 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 -->
<!--
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 -->
## Summary
When the backend serves both `api.stack-auth.com` and `api.hexclave.com`
from the same deployment, signed JWT `iss` claims and OAuth
`redirect_uri` values need to match the host the customer's SDK actually
talks to — otherwise customers with hardcoded issuer checks or
registered OAuth callback URLs break when their SDK upgrades. This PR
makes both follow the request host.
Closes the "Interpretation B" plan from our earlier discussion.
## Changes
### Backend — request-host-derived `iss` and `redirect_uri`
- **New helper**
[`apps/backend/src/lib/request-api-url.ts`](apps/backend/src/lib/request-api-url.ts)
exports `getApiUrlForRequest(req)` and `getApiUrlForHost(host)`. A
consolidated `CLOUD_HOST_PAIRS` constant is the single source of truth
for the stack-auth ↔ hexclave host pairs (prod, dev, staging). Both the
allowlist here and the validator alias map in `tokens.tsx` derive from
it, so they can never drift again.
- **JWT issuer per request**
([`apps/backend/src/lib/tokens.tsx`](apps/backend/src/lib/tokens.tsx)) —
`getIssuer` now takes `apiUrl`.
`generateAccessTokenFromRefreshTokenIfValid` and `createAuthTokens`
accept an `apiUrl` parameter that flows into the `iss` claim.
`getAllowedIssuers` stays env-driven with the bidirectional alias map,
so tokens cross-validate across hosts.
- **OAuth `redirect_uri` per request** — all 12 providers +
`MockProvider` now take `apiUrl` and use it to build `redirect_uri =
apiUrl + "/api/v1/auth/oauth/callback/<provider>"`. `getProvider()`
accepts an `{ apiUrl }` option and forwards it.
- **OAuth2Server factory** — the module-level `oauthServer` singleton
became a per-request `createOAuthServer({ apiUrl })` factory so
`OAuthModel.generateAccessToken` mints tokens with the right `iss`. Used
in the callback route, the token route, and the cross-domain-authorize
helper.
- **Token-minting call sites updated** — all 10 `createAuthTokens`
invocations (password sign-up/sign-in, sessions create,
sessions/current/refresh, anonymous sign-up, apple-native callback,
MFA/OTP/passkey sign-in, OAuth model token exchange), plus the
CLI-complete `generateAccessTokenFromRefreshTokenIfValid` direct call,
now pass `getApiUrlForRequest(fullReq)`.
- **`createVerificationCodeHandler` refactored** to pass `apiUrl` as a
6th positional arg to the user's handler, so MFA/OTP/passkey sign-in
flows get the same per-request `iss` as the rest. The other 8 callers
(password-reset, contact-channels-verify, etc.) don't need changes —
they accept fewer args and TS function-arity compatibility makes that
fine.
### SDK — freeze `@stackframe/*` defaults at stack-auth.com
-
[`packages/template/src/lib/stack-app/apps/implementations/common.ts`](packages/template/src/lib/stack-app/apps/implementations/common.ts)
reverts `defaultBaseUrl` and `defaultAnalyticsBaseUrl` to
`https://api.stack-auth.com` / `https://r.stack-auth.com`. A customer
who upgrades their `@stackframe/*` package to the latest version without
explicitly migrating to `@hexclave/*` keeps hitting `api.stack-auth.com`
and never sees their JWT `iss` or OAuth `redirect_uri` change.
- The `@hexclave/*` mirror packages are unaffected because they were
published from source when `defaultBaseUrl =
"https://api.hexclave.com"`; v1.0.0 already targets the hexclave host on
npm. Extending `scripts/rewrite-packages-to-hexclave.ts` to substitute
these literals during future republishes is a separate follow-up.
### Docs — migration guide rewrite
- [`docs-mintlify/migration.mdx`](docs-mintlify/migration.mdx) rewritten
concisely. Spells out the two host-visible changes that require
pre-deploy action when migrating to `@hexclave/*`: updating manual JWT
verifier code (with the array-of-issuers pattern) and updating OAuth
callback URLs at each provider (with the GitHub-OAuth-Apps single-URL
caveat explicitly called out).
## What was deliberately left out
- **Rewriter pipeline extension** for `@hexclave/*` republishes —
separate follow-up.
- **Cross-SDK defaults** (Swift, stack-cli, init-stack still default to
`api.hexclave.com`) — out of scope per discussion.
- **Dashboard launch-checklist host-awareness** — out of scope per
discussion (callback URLs stay hexclave-branded in the dashboard UI).
## Verification
- `pnpm typecheck` — 29/29 packages pass.
- `pnpm lint` — 29/29 packages pass.
- Five parallel review agents (JWT, OAuth, helper, migration guide, SDK
defaults) + an external review of the commit caught four real issues —
all resolved in the same commit before push:
- Missing `api.staging.*` entries in `issuerHostAliases` (would have
broken cross-host token validation on staging).
- Stale comment in `apps/backend/src/stack.tsx`.
- Misleading "backward-compat" comment in `getHardcodedFallbackUrls`.
- MFA/OTP/passkey using env-var fallback for `iss` instead of the
request host.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Makes JWT issuers and OAuth redirect_uri values follow the incoming
request’s host so tokens and redirects always match `api.stack-auth.com`
or `api.hexclave.com`. Also freezes `@stackframe/*` SDK defaults to
Stack Auth and tightens the migration guide to focus on OAuth callbacks.
- **New Features**
- Added `request-api-url` helper with an allowlist of cloud hosts;
unknown hosts fall back to the deployment’s API URL.
- JWT `iss` now uses the per-request API URL; validation accepts both
brands via aliases derived from one `CLOUD_HOST_PAIRS` source.
- All OAuth providers build `redirect_uri` from the request host;
`getProvider()` now takes `{ apiUrl }`.
- Replaced the OAuth2Server singleton with per-request
`createOAuthServer({ apiUrl })` so token exchange mints with the right
issuer.
- Updated token-minting and OAuth routes to pass the API URL;
verification-code flows receive it; connected-accounts refresh paths
safely pin the deployment default.
- SDK: `@stackframe/*` defaults point to `https://api.stack-auth.com`;
`@hexclave/*` mirrors remain hexclave-branded.
- Shared: updated fallback API host lists to include both stack-auth and
hexclave hosts.
- **Migration**
- Update each provider’s OAuth callback URL to
`https://api.hexclave.com/api/v1/auth/oauth/callback/<provider>` when
migrating to `@hexclave/*`.
- If you verify JWTs manually, update the expected issuer to the
hexclave host (including anonymous/restricted variants).
<sup>Written for commit e42dfaf05b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/hexclave/stack-auth/pull/1498?utm_source=github">Review
in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Per-request API host awareness so tokens and OAuth flows reflect the
incoming request’s canonical API URL.
* **Updates**
* OAuth providers and servers now derive callback/redirect URLs from
request context rather than a static URL.
* Token issuance/validation now embeds and accepts host-specific issuer
URLs and paired host aliases for rebrand compatibility.
* **Documentation**
* Migration guide updated for branding, JWT issuer expectations, and
OAuth callback guidance.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1498?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 -->
## What
1. **Backend dual-accept**: `isAcceptedNativeAppUrl()` accepts both
`stack-auth-mobile-oauth-url://` (legacy) and
`hexclave-mobile-oauth-url://` (canonical).
2. **Swift SDK switches to the canonical scheme**: `StackAuth` Swift SDK
now emits and intercepts `hexclave-mobile-oauth-url://` for native-app
OAuth callbacks.
Before this PR, `hexclave-mobile-oauth-url` existed only inside
`RENAME-TO-HEXCLAVE.md` — not in any code.
## Why the Swift SDK change is safe
The Swift SDK uses
`ASWebAuthenticationSession(url:callbackURLScheme:completion:)`
([StackClientApp.swift:197-199](sdks/implementations/swift/Sources/StackAuth/StackClientApp.swift#L197)).
With this API, iOS intercepts the callback scheme **ephemerally** — no
`Info.plist` registration is required. The Swift SDK source has no
`Info.plist`, and the example apps' `pbxproj` registers no
`CFBundleURLSchemes`. So:
- New customer builds against the updated SDK → emit new scheme →
backend accepts → `ASWebAuthenticationSession` intercepts on new scheme
→ works.
- Already-shipped customer App Store binaries on older SDK versions →
emit old scheme → backend still accepts → works.
- **No customer ever has to update an `Info.plist`.**
The only real backward-compat constraint is that the backend can never
drop the old scheme (already-shipped customer binaries have the constant
baked into them). Hence the dual-accept.
(Note: `RENAME-TO-HEXCLAVE.md` line 88 incorrectly attributes the
constraint to `Info.plist` registration. That's not how the SDK works —
the scheme is baked into the SDK binary, not the customer's plist. The
fix described in that doc is essentially the right shape; only the
mechanism description is wrong.)
## Changes
| File | Change |
|---|---|
| `packages/stack-shared/src/utils/redirect-urls.tsx` |
`isAcceptedNativeAppUrl()` accepts either protocol. |
| `apps/backend/src/lib/redirect-urls.test.tsx` | Adds positive
assertions for the new scheme in `isAcceptedNativeAppUrl`; parity
negative assertions in `validateRedirectUrl`. |
| `sdks/implementations/swift/Sources/StackAuth/StackClientApp.swift` |
`callbackScheme` → `"hexclave-mobile-oauth-url"`; fatalError example
strings updated. |
| `sdks/implementations/swift/Tests/StackAuthTests/OAuthTests.swift` |
Test fixture URLs updated (no assertions depend on the scheme literal).
|
|
`sdks/implementations/swift/Examples/StackAuthiOS/.../StackAuthiOSApp.swift`
| Default values in the example UI. |
|
`sdks/implementations/swift/Examples/StackAuthMacOS/.../StackAuthMacOSApp.swift`
| Default values in the example UI. |
| `sdks/implementations/swift/README.md` | Documents the new canonical
scheme; compat note for the legacy one. |
| `sdks/spec/src/apps/client-app.spec.md` | New scheme is canonical;
legacy is "accepted indefinitely for already-shipped customer app
binaries built against older SDK versions." |
## Verification
- `pnpm test run apps/backend/src/lib/redirect-urls.test.tsx` — 34/34
passing (was 33; one new `it` block plus parity assertions).
- `pnpm --filter @stackframe/stack-shared --filter @stackframe/backend
run lint` — clean.
- `pnpm --filter @stackframe/stack-shared --filter @stackframe/backend
run typecheck` — clean.
- Swift assertions in `OAuthTests.swift` do not check the scheme literal
— they only check `oauth/authorize/<provider>`, state/verifier
non-emptiness, and that `redirectUrl` round-trips. The fixture-value
change is mechanical.
## Risk
Low. Backend behavior strictly widens (every URL accepted before is
still accepted). Swift SDK change is internal to OAuth callback
handling, requires no customer migration, and is paired with the backend
dual-accept landing in the same PR.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Adopted the canonical OAuth callback scheme
"hexclave-mobile-oauth-url://" for native apps while continuing to
accept the legacy "stack-auth-mobile-oauth-url://".
* **Documentation**
* Updated SDK docs, examples, and spec guidance to reference the
canonical callback scheme and clarify legacy acceptance.
* **Tests & Samples**
* Updated tests and example apps to use and validate the canonical
scheme.
* **Style**
* Rebranded the dev-tool trigger icon to the new Hexclave monochrome
logo.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1501?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 -->
