mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-13 21:01:21 +08:00
8052a2be62
Some checks failed
all-good: Did all the other checks pass? / all-good (push) Has been cancelled
Ensure Prisma migrations are in sync with the schema / check_prisma_migrations (22.x) (push) Has been cancelled
DB migration compat / Check if migrations changed (push) Has been cancelled
Docker Server Build and Push / Docker Build and Push Server (push) Has been cancelled
Docker Server Build and Run / docker (push) Has been cancelled
Runs E2E API Tests / E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }}) (mock, 22.x) (push) Has been cancelled
Runs E2E API Tests / E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }}) (prod, 22.x) (push) Has been cancelled
Runs E2E API Tests with custom port prefix / build (22.x) (push) Has been cancelled
Lint & build / lint_and_build (latest) (push) Has been cancelled
Dev Environment Test With Custom Base Port / restart-dev-and-test-with-custom-base-port (push) Has been cancelled
Dev Environment Test / restart-dev-and-test (push) Has been cancelled
Run setup tests with custom base port / setup-tests-with-custom-base-port (push) Has been cancelled
Run setup tests / setup-tests (push) Has been cancelled
TOC Generator / TOC Generator (push) Has been cancelled
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
DB migration compat / No migration changes (skipped) (push) Has been cancelled
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **High Risk**
> Touches authentication and OAuth token/authorize flows and changes how
client requests are validated, so regressions could cause widespread
login/client-access failures. Also includes a data migration that alters
effective security posture for existing projects.
>
> **Overview**
> Adds a **project-level toggle**
(`project.requirePublishableClientKey`) to control whether client
requests/OAuth flows must include a publishable client key, including a
DB migration that backfills existing projects to require it.
>
> Backend auth now treats the publishable client key as *optional when
allowed*, introducing a public sentinel (`__stack_public_client__`) and
returning a new specific error
(`PUBLISHABLE_CLIENT_KEY_REQUIRED_FOR_PROJECT`) across smart request
auth + OAuth `authorize`/`callback`/`token` endpoints.
>
> Dashboard and SDKs update key generation/display and request
construction to handle missing publishable keys, expose an advanced
toggle on the Project Keys page, and extend internal config overrides to
support a new `project` level; E2E/tests and schema fuzzing are expanded
accordingly, and CI adds a forward-compat migration check job when
back-compat fails.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
|
||
|---|---|---|
| .. | ||
| src | ||
| package.json | ||
| 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 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 Stack Auth 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