mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-13 21:01:21 +08:00
c0fefd3b7a
## 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 --> |
||
|---|---|---|
| .. | ||
| src | ||
| package.json | ||
| README.md | ||
Hexclave SDK Specification
This folder contains the specification for Hexclave's SDKs.
When writing this specification, try to write imperative pseudocode as much as possible (be explicit about what things are named, etc.).
Notation
The spec files use the following notation:
| Notation | Meaning |
|---|---|
[authenticated] |
Include access token, handle 401 refresh |
[server-only] |
Requires secretServerKey |
[BROWSER-LIKE] |
Requires browser or browser-like environment (browser, WebView, in-app browser). On mobile, open an in-app browser (ASWebAuthenticationSession on iOS, Custom Tabs on Android). On desktop, open the system browser with a registered URL scheme. |
[BROWSER-ONLY] |
Strictly requires browser environment (DOM, window object) |
[CLI-ONLY] |
Only in languages/platforms with an interactive terminal |
[JS-ONLY] |
Only available in the JavaScript SDK |
{ field, field } |
Request body (JSON) |
"Does not error" |
Function handles errors internally |
"Errors: ..." |
Lists possible errors with code/message |
See _utilities.spec.md for more details.
Language Adaptation
The languages should adapt:
- Naming conventions: camelCase (JS), snake_case (Python), PascalCase (Go), etc.
- Async patterns: Promises (JS), async/await (Python), goroutines (Go)
- Error handling: Exceptions vs Result types (language preference)
- Parameter conventions: Objects vs. kwargs, etc.
- Framework hooks: Eg. for React, add
use*equivalents toget*/list*methods - Everything else, wherever it makes sense: Every language is unique and the patterns will differ. If you have to decide between what's idiomatic in a language vs. what was done in the Hexclave SDK for other languages, use the idiomatic pattern.
Implementation Notes
Object Construction
When constructing SDK objects (User, Team, etc.) from API responses:
- Map naming conventions to your language's naming convention
- Objects should hold a reference to the SDK client for making API calls
- Objects can be mutable or immutable based on language conventions
update()methods should update local properties after successful API call
Caching
Normal functions should not cache. Some frameworks, like React, have hooks that require caching; for these, require explicit guidance.
Pagination
Most list* methods support pagination:
- Request with
cursorandlimitquery params - Response includes
pagination: { next_cursor?: string } next_cursoris null or absent when no more pages- Default limit is typically 100
- Note that not all backend APIs support pagination, and some just return all items at once.
Date/Time Formats
- API uses milliseconds since epoch for timestamps (e.g.,
signed_up_at_millis) - Convert to your language's native Date/DateTime type