CodeCow/stack
1
0
Fork 0
mirror of https://github.com/stack-auth/stack.git synced 2026-06-16 21:08:38 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
7891d2cc99
stack/sdks/spec
History
Mantra 7f8e3df852
feat: add anonRefreshToken to CLI auth flow and enhance session management (#1303) 
- Extended `CliAuthAttempt` with `anonRefreshToken` and a migration.
- CLI `POST /auth/cli` accepts optional `anon_refresh_token` (must be an
anonymous user's refresh token for the current project).
- `POST /auth/cli/complete` supports `mode` `check` (anonymous vs none),
`claim-anon-session` (issue tokens for the linked anonymous session),
and `complete` (bind the browser session's refresh token to the
attempt). Completing clears `anonRefreshToken` on the row. We do **not**
merge anonymous account data into the signed-in user (that behavior was
removed as a security risk; the anonymous user remains unchanged).
- Template CLI confirmation page, stack-cli optional
`STACK_CLI_ANON_REFRESH_TOKEN`, SDK/spec updates, and e2e coverage.

<!--

Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md

-->


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

* **New Features**
* CLI login supports attaching anonymous sessions and a multi-mode
confirm/claim/check flow; CLI tools now surface login codes and remove
anon token after use.
  * Added interactive CLI auth demo page and a CLI simulator script.
* Client libraries: prompt flow accepts an optional anon token and a
promptLink(url, loginCode) callback.

* **Tests**
* Expanded end-to-end coverage for anonymous CLI sessions,
claim/complete/poll flows, upgrades, and error cases.

* **Documentation**
* Updated prompt CLI docs/spec to describe new options and callback
signature.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-04-14 02:09:35 +00:00
..
src feat: add anonRefreshToken to CLI auth flow and enhance session management (#1303) 2026-04-14 02:09:35 +00:00
package.json chore: update package versions 2026-04-13 11:31:28 -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