CodeCow/stack
1
0
Fork 0
mirror of https://github.com/stack-auth/stack.git synced 2026-06-04 21:04:37 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
promptless/document-cli-init-options
stack/sdks/spec
History
Mantra e2dc5f5ee0
[codex] fix OAuth redirect contract (#1393) 
## Summary

- Route browser OAuth redirects through the configured `redirectMethod`
instead of hardcoded `window.location` calls.
- Keep OAuth redirect APIs pending after navigation starts, including
custom redirect methods.
- Add `cliAuthConfirm` handler URL metadata and custom-page prompt
coverage.
- Update SDK spec text for browser OAuth callback and `returnTo`
behavior.

## Root Cause

OAuth helpers previously combined URL construction with direct browser
navigation. That bypassed configured redirect methods and made it too
easy for public redirect APIs to resolve after navigation started.

## Impact

Browser SDK consumers get consistent redirect behavior across built-in
and custom navigation methods. `returnTo` is handled as the
post-callback destination while the OAuth callback URL remains fixed to
the configured handler route.

## Validation

- `pnpm test run packages/template/src/lib/auth.test.ts`
- `pnpm test run apps/e2e/tests/js/oauth.test.ts`
- `pnpm -C packages/template lint`
- `pnpm -C apps/e2e lint`
- `pnpm -C packages/template typecheck`
- `pnpm -C apps/e2e typecheck`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added CLI authorization confirmation page/flow for terminal-based
auth.
* Added optional returnTo parameter for OAuth to control post-auth
redirects.
* Exposed configurable redirect behavior so apps follow the chosen
redirect method.

* **Bug Fixes**
* OAuth callback now uses app navigation/queued redirects and shows a
fallback link instead of forcing location.assign.

* **Tests**
* Added unit and e2e tests covering OAuth URL generation, scope
handling, and CLI auth confirmation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-04-28 16:33:59 -07:00
..
src [codex] fix OAuth redirect contract (#1393) 2026-04-28 16:33:59 -07:00
package.json chore: update package versions 2026-04-20 19:06:56 -07:00
README.md [Fix] [Feat] Update OAuth Sign-In and Get Token Functions to Work (#1130) 2026-01-28 02:17:27 +00:00

README.md

Stack Auth SDK Specification

This folder contains the specification for Stack Auth'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 to get*/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 Stack Auth SDK for other languages, use the idiomatic pattern.

Implementation Notes

Object Construction

When constructing SDK objects (User, Team, etc.) from API responses:

  1. Map naming conventions to your language's naming convention
  2. Objects should hold a reference to the SDK client for making API calls
  3. Objects can be mutable or immutable based on language conventions
  4. 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 cursor and limit query params
  • Response includes pagination: { next_cursor?: string }
  • next_cursor is 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