feat(backend): dual-accept hexclave-mobile-oauth-url:// alongside legacy scheme#1501
Merged
Conversation
…acy scheme The mobile OAuth URL scheme is a Tier 0 wire identifier (see RENAME-TO-HEXCLAVE.md). It is baked into customer iOS/macOS apps via Info.plist, so the backend must accept the new canonical 'hexclave-mobile-oauth-url://' without ever dropping the legacy 'stack-auth-mobile-oauth-url://' — removing the latter would break OAuth for every already-shipped customer app built against the frozen StackAuth Swift SDK. - packages/stack-shared: isAcceptedNativeAppUrl() now returns true for either protocol. - apps/backend tests: assert the new scheme is accepted by isAcceptedNativeAppUrl and (parity with old) rejected by validateRedirectUrl in the no-trusted-domain case. - sdks/spec/client-app.spec.md: document both schemes; canonical for new SDKs is the Hexclave one. Out of scope: the frozen StackAuth Swift SDK keeps registering and emitting the legacy scheme; the new Hexclave Swift package (which will use the new scheme) is not yet created.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds canonical ChangesNative app OAuth redirect URL scheme support
Dev tool rebrand
Sequence Diagram(s)sequenceDiagram
participant ClientApp
participant ASWebAuthenticationSession
participant Backend_validateRedirectUrl
ClientApp->>ASWebAuthenticationSession: open OAuth (callbackScheme: hexclave-mobile-oauth-url / stack-auth-mobile-oauth-url)
ASWebAuthenticationSession->>Backend_validateRedirectUrl: submit redirect URL for validation
Backend_validateRedirectUrl-->>ASWebAuthenticationSession: validation result (accepted / rejected)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR widens
Confidence Score: 5/5Safe to merge — the change adds exactly one new accepted scheme string and cannot remove or alter any previously accepted URL. The core edit is a two-line OR-check on an exact url.protocol comparison, well-tested with both positive and negative assertions, and the existing Swift SDK is intentionally left untouched so no live traffic path changes. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Native App sends OAuth callback URL] --> B{isAcceptedNativeAppUrl?}
B --> C{url.protocol === 'stack-auth-mobile-oauth-url:'}
B --> D{url.protocol === 'hexclave-mobile-oauth-url:'}
C -- Yes --> E[Accept - Legacy SDK]
D -- Yes --> F[Accept - Canonical Hexclave SDK]
C -- No --> G{Either matched?}
D -- No --> G
G -- Neither --> H[Reject]
Reviews (1): Last reviewed commit: "feat(backend): dual-accept hexclave-mobi..." | Re-trigger Greptile |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/backend/src/lib/redirect-urls.test.tsx`:
- Around line 637-640: The legacy-scheme test in redirect-urls.test.tsx is
missing an assertion for the legacy oauth-callback path; update the "should
accept the legacy native app OAuth URL scheme" test that calls
isAcceptedNativeAppUrl to include
expect(isAcceptedNativeAppUrl('stack-auth-mobile-oauth-url://oauth-callback')).toBe(true)
alongside the existing 'success' and 'error' assertions so the legacy scheme has
parity with the canonical oauth-callback coverage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9494bc71-361c-434a-bc44-8661b3a853ca
📒 Files selected for processing (3)
apps/backend/src/lib/redirect-urls.test.tsxpackages/stack-shared/src/utils/redirect-urls.tsxsdks/spec/src/apps/client-app.spec.md
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 3 files
Tip: cubic could auto-approve low-risk PRs like this, if it thinks it's safe to merge. Learn more
Re-trigger cubic
…orten backend comment Builds on the previous commit. Backend now accepts both schemes, so the StackAuth Swift SDK can safely emit the canonical hexclave-mobile-oauth-url scheme without breaking already-shipped customer App Store binaries (those still emit the legacy scheme and the backend still accepts it). ASWebAuthenticationSession's callbackURLScheme: parameter intercepts the callback ephemerally, so no customer Info.plist change is required. - StackClientApp.swift: callbackScheme constant + fatalError example strings. - OAuthTests.swift: test fixture URLs (no assertions depend on the scheme). - StackAuthiOSApp.swift / StackAuthMacOSApp.swift: default values in the example UIs. - swift/README.md: docs point at the new scheme; compat note mentions the legacy one. - spec/client-app.spec.md: tightened wording — old scheme is for already-shipped binaries, not 'the frozen StackAuth Swift SDK' (which now also emits the new scheme). - redirect-urls.tsx: shortened the dual-accept comment to one line.
The spec is the source of truth for generating SDK implementations; it should describe the canonical wire behavior only. Backend dual-accept of the legacy 'stack-auth-mobile-oauth-url://' scheme is a backend implementation detail (documented in the code comment at packages/stack-shared/src/utils/redirect-urls.tsx) and git history preserves the previous spec wording. New SDK authors reading this spec now see one canonical scheme.
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
sdks/implementations/swift/Sources/StackAuth/StackClientApp.swift (1)
189-199:⚠️ Potential issue | 🔴 CriticalEnsure example iOS/macOS apps register
hexclave-mobile-oauth-urlinCFBundleURLSchemes
StackClientApp.swiftsetscallbackScheme = "hexclave-mobile-oauth-url"and uses it for both the OAuth redirect URLs andASWebAuthenticationSession(callbackURLScheme:). The example apps’Info.plistfiles undersdks/implementations/swift/Examples/StackAuthiOSandsdks/implementations/swift/Examples/StackAuthMacOSmust includehexclave-mobile-oauth-urlinCFBundleURLSchemes; a targeted search of those exampleInfo.plistfiles returned no matches, so OAuth callback routing is likely to fail.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@sdks/implementations/swift/Sources/StackAuth/StackClientApp.swift` around lines 189 - 199, The app uses callbackScheme = "hexclave-mobile-oauth-url" in StackClientApp.swift (used in getOAuthUrl redirectUrl and ASWebAuthenticationSession(callbackURLScheme:)), but the example iOS and macOS apps must register that scheme in their Info.plist; open the Example targets (StackAuthiOS and StackAuthMacOS) Info.plist files and add "hexclave-mobile-oauth-url" under CFBundleURLTypes → CFBundleURLSchemes so the ASWebAuthenticationSession callback and OAuth redirects resolve correctly.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@sdks/implementations/swift/Sources/StackAuth/StackClientApp.swift`:
- Around line 189-199: The app uses callbackScheme = "hexclave-mobile-oauth-url"
in StackClientApp.swift (used in getOAuthUrl redirectUrl and
ASWebAuthenticationSession(callbackURLScheme:)), but the example iOS and macOS
apps must register that scheme in their Info.plist; open the Example targets
(StackAuthiOS and StackAuthMacOS) Info.plist files and add
"hexclave-mobile-oauth-url" under CFBundleURLTypes → CFBundleURLSchemes so the
ASWebAuthenticationSession callback and OAuth redirects resolve correctly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1fcc1ffc-7072-4e5a-960c-4a03e39691d0
📒 Files selected for processing (7)
packages/stack-shared/src/utils/redirect-urls.tsxsdks/implementations/swift/Examples/StackAuthMacOS/StackAuthMacOS/StackAuthMacOSApp.swiftsdks/implementations/swift/Examples/StackAuthiOS/StackAuthiOS/StackAuthiOSApp.swiftsdks/implementations/swift/README.mdsdks/implementations/swift/Sources/StackAuth/StackClientApp.swiftsdks/implementations/swift/Tests/StackAuthTests/OAuthTests.swiftsdks/spec/src/apps/client-app.spec.md
✅ Files skipped from review due to trivial changes (3)
- sdks/implementations/swift/README.md
- sdks/implementations/swift/Examples/StackAuthMacOS/StackAuthMacOS/StackAuthMacOSApp.swift
- sdks/spec/src/apps/client-app.spec.md
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/stack-shared/src/utils/redirect-urls.tsx
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
…uth glyph The dev-tool floating trigger button was still rendering the old stacked-layers Stack Auth mark even after the rest of the dev tool (aria-label, title, storage keys, docs URL) was rebranded to Hexclave. Replace STACK_LOGO_SVG with HEXCLAVE_LOGO_SVG — a monochrome currentColor rendering of the hexagon-with-three-radial-bars benzene mark from apps/dashboard/public/hexclave-icon.svg. Gradient and glow are stripped because the trigger glyph is 22x22 inside a colored chip with color: white, so a flat monochrome reads better at that size.
N2D4
approved these changes
May 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
isAcceptedNativeAppUrl()accepts bothstack-auth-mobile-oauth-url://(legacy) andhexclave-mobile-oauth-url://(canonical).StackAuthSwift SDK now emits and interceptshexclave-mobile-oauth-url://for native-app OAuth callbacks.Before this PR,
hexclave-mobile-oauth-urlexisted only insideRENAME-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). With this API, iOS intercepts the callback scheme ephemerally — noInfo.plistregistration is required. The Swift SDK source has noInfo.plist, and the example apps'pbxprojregisters noCFBundleURLSchemes. So:ASWebAuthenticationSessionintercepts on new scheme → works.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.mdline 88 incorrectly attributes the constraint toInfo.plistregistration. 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
packages/stack-shared/src/utils/redirect-urls.tsxisAcceptedNativeAppUrl()accepts either protocol.apps/backend/src/lib/redirect-urls.test.tsxisAcceptedNativeAppUrl; parity negative assertions invalidateRedirectUrl.sdks/implementations/swift/Sources/StackAuth/StackClientApp.swiftcallbackScheme→"hexclave-mobile-oauth-url"; fatalError example strings updated.sdks/implementations/swift/Tests/StackAuthTests/OAuthTests.swiftsdks/implementations/swift/Examples/StackAuthiOS/.../StackAuthiOSApp.swiftsdks/implementations/swift/Examples/StackAuthMacOS/.../StackAuthMacOSApp.swiftsdks/implementations/swift/README.mdsdks/spec/src/apps/client-app.spec.mdVerification
pnpm test run apps/backend/src/lib/redirect-urls.test.tsx— 34/34 passing (was 33; one newitblock 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.OAuthTests.swiftdo not check the scheme literal — they only checkoauth/authorize/<provider>, state/verifier non-emptiness, and thatredirectUrlround-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.
Summary by CodeRabbit
New Features
Documentation
Tests & Samples
Style