<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **High Risk**
> Touches core sign-up/auth flows and user restriction semantics
(including new DB constraints) and introduces dynamic rule
evaluation/logging; misconfiguration or CEL/parser bugs could block
sign-ups or incorrectly restrict users.
>
> **Overview**
> Introduces **CEL-based sign-up rules** (config-driven) that are
evaluated during password/OTP/OAuth sign-ups and anonymous upgrades;
matching rules can reject sign-ups or mark users as admin-restricted,
and triggers are logged for analytics.
>
> Extends `ProjectUser` with `restrictedByAdmin` plus public/private
restriction details, updates restriction computation/filtering, and
exposes these fields via user CRUD (including validation + DB constraint
enforcing consistency when unrestricted).
>
> Adds a new dashboard **Sign-up Rules** page with a visual condition
builder (CEL <-> visual tree), drag-reorder by priority, per-rule 48h
sparkline analytics via a new hidden internal endpoint, and adds
user-page UI to view/edit manual restrictions. Also refactors ClickHouse
client initialization to require env vars (removing
`isClickhouseConfigured` checks) and adjusts CI container startup wait
time.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
2141e689e8c1b72303b805e9234f996010d0880. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Sign-up Rules: visual rule builder, in-project CRUD with drag-reorder,
per-rule analytics, backend evaluation, and admin UI.
* Admin user restrictions: dashboard controls, banners/status,
public/private admin details surfaced in user views.
* **APIs & Schema**
* Config and user schemas extended; new SignUpRejected error and sign-up
rule types added.
* **Tests**
* Extensive unit and E2E coverage for rules, parser, evaluator,
analytics, and restricted-user flows.
* **Docs**
* Editorial guidance added to AGENTS.md.
* **Chores**
* DB statement timeout, updated clean script, minor dependency
additions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
### Context
We noticed some errors pop up on sentry related to email rendering.
These errors seem to have been triggered by the same issue, and could be
categorized as follows:
1. Sanity test mismatch, even when the errors from freestyle and vercel
sandbox were broadly similar. This occurred due to stack traces
differing in different execution environments.
2. Rendering errors from freestyle and vercel sandbox caused by the
theme not being imported/ empty theme component.
Upon investigation, this occurred because hitting save on the email
themes page with an invalid theme (ex: deleting the `export` keyword, or
renaming the `EmailTheme` component) still triggers `bundleAndExecute`
with the invalid themes. This will obviously fail and cause the errors
to be logged, however there is no cause for concern here because the
error is returned and the save is denied because an error is returned.
It's more of a matter of noisy error logs and too strict sanity test
comparisons.
Beyond that, `js-execution` is a little opaque and hard to understand,
and this can mask errors in logic.
We also noticed a new issue: manually throwing an error in the email
theme code editor, and then trying to save was actually successful. This
was because the version of `react-email/components` we were using had
faulty error handling, and fell back to client side rendering, masking
the error. This wasn't caught by our `try-catch` safeguards because it
was a render time issue that was masked. More specifically, this was
what `react-email` was doing: `Switched to client rendering because the
server rendering errored`.
### Summary of Changes
We loosen the sanity test comparison between engine execution results in
case of errors. We then refactor the `js-execution` and
`email-rendering` files to read better, and to only `captureError` when
a service is down, but not for runtime errors in the user submitted
code.
To deal with the other bug, we bumped `react-email/components` to the
latest version. However, doing so exposed a gap between real `freestyle`
and our `freestyle-mock`: with the mock, the errors that were now raised
were treated as uncaught exceptions, crashing the mock server.
Consequently, we switched to using `node` over `bun`.
We also expanded test coverage to account for different error paths.
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
Possible CI flake fix: track external DB sync cleanup per test suite to
avoid cross-suite config resets.\n\n- Lint: pass\n- Typecheck: pass
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added external database synchronization, enabling data replication
from the internal database to external PostgreSQL databases with
incremental batching and sequence tracking.
* Introduced background cron job execution system for scheduled tasks.
* **Tests**
* Added comprehensive test suites for external database synchronization
scenarios including basic operations, advanced configurations,
high-volume data transfers, and race condition handling.
* **Chores**
* Enhanced CI/CD workflows to support external database sync operations.
* Updated Docker configuration and environment variables for improved
testing infrastructure.
* **Bug Fixes**
* Increased test timeout threshold for session expiration tests to
accommodate slower executions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
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**
* Added a dedicated endpoint to retrieve query timing statistics using
query identifiers.
* Query responses now include a unique query_id for tracking and
reference.
* **Improvements**
* Query timeout validation now enforces a maximum limit of 2 minutes.
* Query response structure updated to support separate timing
information retrieval.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
https://www.loom.com/share/bb7abfde507f40d386ee856f5ffbd506
<!--
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**
* USD-based refund system enabling partial and full refunds with
explicit USD amounts
* Per-entry refund selection with granular quantity controls in refund
dialogs
* **Bug Fixes**
* Stronger refund validation and error handling to prevent invalid or
out-of-bounds refunds
* **Tests**
* Expanded end-to-end coverage for refund edge cases and scenarios
* **Style**
* Improved refund dialog UI with contextual alerts and better controls
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
DB migrations are backwards-compatible / Test migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
### Summary of Changes
Previously, on the Swift SDK, the `signInWithOAuth` function wasn't
working. In this PR, we fix it by having the `getOAuthUrl` function to
actually redirect correctly. Note that to do so, we updated the
`validRedirectUrl` check on the backend to accept app native redirects
(from our new trusted url scheme). Another thing to note is that we
added functionality to the `TokenStore` abstraction to conditionally
refresh the access token that the user is trying to fetch if it is
expired/close to expiring if possible. `getOAuthUrl` will attempt to get
a valid access token, and thus will rely on our algorithm documented in
`utilities.md`.
The specs serve as the source of truth.
We go further and implement Apple Native sign in. To do so, we have it
hit a new route on the backend and verify the `jwtToken` retrieved by
the sdk against an Apple-provided set of `jwks`. We use jose to do so,
in line with the rest of the codebase.
We take this opportunity to refactor the oauth provider route owing to
the amount of duplicated logic. Additionally, to enable the apple sign
in, users will have to update the Apple authentication method modal on
the dashboard and add accepted bundle ids. These are identifiers for
projects, and we will check the `JWT` on the backend to make sure the
audience is set to an accepted bundleId.
We also update the Apple modal to be more informative.
### Using the new Features
To use the Apple native sign in, users will have to 1) sign up with an
apple developer account, 2) set up their bundleids for their projects by
connecting them to the apple developer account, 3) update the Stack-Auth
Authentication Methods dashboard apple modal with the relevant fields.
Then, trying to sign in with apple with our Swift SDK will use the apple
native sign in.
### UI Changes
Renamed the fields in the apple modal. Added a new field for bundle ids.
See below.
https://github.com/user-attachments/assets/0e760c0e-3198-4818-ac7f-4900d7a125bb
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
<!--
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
* **Security**
* Added client-side access checks on payments endpoints and expanded
customer-type handling (including a new "custom" type).
* **SDK / Client**
* Client interface methods now accept explicit request types
(client/server/admin) to route requests appropriately.
* **Server**
* New server-side product listing to support server requests and
caching.
* **Tests**
* E2E tests updated to use a fast sign-up flow and pass authentication
tokens for authorized requests.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<img width="553" height="471" alt="Screenshot 2026-01-14 at 12 16 36 PM"
src="https://github.com/user-attachments/assets/9f32473d-5294-4cf7-b527-0668fb04ae47"
/>
<img width="630" height="514" alt="Screenshot 2026-01-14 at 12 17 06 PM"
src="https://github.com/user-attachments/assets/b17f57f7-148d-4438-b337-df7516d1793e"
/>
<!--
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**
* Expanded Stripe webhooks: handles invoice and one‑time/subscription
events, sends templated payment receipt and failure emails, posts
chargeback alerts to Telegram.
* Customer invoices API plus client and UI support for listing invoices;
backend stores invoice status, total, and hosted URL.
* **Tests**
* Added end‑to‑end tests for new webhook scenarios (receipts, failures,
chargebacks) and invoices API with email outbox checks.
* **Chores**
* Centralized Telegram helpers and improved formatting, validation, and
reliability.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Introduces end-to-end invoice visibility and payment notifications.
>
> - **Emails:** Adds default `payment_receipt` and `payment_failed`
templates and sends them from Stripe webhooks for one-time and
subscription payments (skips non‑uncollectible failures); resolves
recipients for users/teams.
> - **Webhooks:** Expands handled events; upserts invoices on
`invoice.*`; stricter unknown-type handling; adds Telegram chargeback
alert; refactors init script Telegram sending.
> - **Data model:** Extends `SubscriptionInvoice` with `status`,
`amountTotal`, `hostedInvoiceUrl` and writes them via
`upsertStripeInvoice`.
> - **API/SDK/UI:** New paginated `GET
/payments/invoices/{customer_type}/{customer_id}`; client interface
(`listInvoices`, hooks) and template Payments panel render an invoices
table.
> - **Tests:** E2E for invoices access, webhook behaviors, and email
delivery.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
edc8fe5651. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
### Summary of Changes
We would like to setup a payment settings page. Here, developers should
be able to toggle test mode, see their stripe connection status, and
adjust the payment method configs.
## Test Mode Toggle
This will exist in concert with the test mode banner.
## Stripe Connection Status
While users cannot see the page unless they create a stripe account,
they can still see it if they've created the stripe connected account
but haven't finished onboarding. This is a handy place for them to
finish their onboarding.
## Payment Methods
We would like developers using our payments feature to be able to set
what payment options should be made available to their users.
Consequently, we create a route and a page on the dashboard which hits
that route to update what payment options are made available. The UI
stores "pending changes" which represent updates to be made to the
payment method configs corresponding to that project's connected stripe
account. These are then sent to the backend, validated with a schema,
and then updated using stripe.
We also note that some payment methods have dependencies on others: for
example, the "apple pay" method cannot be enabled if the "debit/credit
cards" method is not enabled. We note the two cases where it is observed
to happen and raise an alert using `toast` to make it clear to the
developer, and make it extensible in case other dependencies are added
in the future. To ensure synchronization between the frontend dashboard
UI and the backend route handler on the payment method names, we have
both pull from a shared utility file. This ensures only one update will
need to be made.
**NOTE 1:** We chose to build our own component rather than using the
Stripe embedded component as the Stripe component is still in
pre-release mode.
**NOTE 2:** To disable specific payment methods for all our users, we
should update the platform account config in Stripe for stack-auth. This
will prevent said payment method from being made available to them.
**NOTE 3:** We skip the multi-account method config isolation test
because the stripe mock server does not support testing with multiple
accounts. However, the logic of the test has been verified with a real
stripe account.
### UI Demo
For this demo, I had a pre-created checkout link for a one-time purchase
of a product for 100$.
https://github.com/user-attachments/assets/a0139ee8-a9ce-480c-b8b5-9b5fb1e9c15f
<!--
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
* **Refactor**
* Centralized email-theme operations (create/read/list/update/delete)
behind a unified handler, simplifying endpoints and improving
consistency.
* **New Features**
* Theme updates now validate and render template previews before
applying changes; create supports generated or provided IDs.
* **Chores**
* Added a reusable CRUD handler factory to standardize backend
data-operation patterns and error handling.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
### Summary of Changes
We had an issue with a test being exceedingly flaky. This was a result
of not enough time having passed between the email being put up for
rendering/ being evaluated for skipped status and it being checked.
Polling reduces our dependency on arbitrary timeout periods. This is in
line with how we poll the inbox in other tests (see
`waitForMessagesWithSubject` in `helpers.ts`). It doesn't solve
flakiness because flakiness is a result of the indeterminism of what
we're testing.
Previously, we were using an old version of `freestyle.sh` and
experienced issues with it failing. We want to update it to the latest
API and also introduce a fallback that can be used when freestyle fails
to improve reliability. We refactor the `freestyle.tsx` wrapper code
around `freestyle` to a `js-execution-engine`, which also offers
opportunities to extend the email rendering engine abstraction in the
future. If `freestyle` encounters runtime errors while running the code
or fails, we retry once and then default to `Vercel sandbox`. Note that
we also introduce a sanity test: 5% of the time, we will run the code
through both `freestyle` and the `Vercel Sandbox` and log it if the
results don't match.
As a chore, we also up the time limit on a `failed-email-digest.test.ts`
test to make it less flakey.
https://www.loom.com/share/f218c4d16b4d4306be93685aad7aed7a
<!--
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**
* One-click subscription switching (client + server) and UI dialog to
choose alternative plans
* Products now show available plan alternatives (switch options)
* **Improvements**
* More robust default payment-method handling, validation, and clearer
errors when none is set
* Improved payment-method retrieval and customer metadata persistence
* **Tests**
* End-to-end tests for plan switching and updated billing snapshots
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<img width="1193" height="827" alt="Screenshot 2026-01-09 at 1 46 38 PM"
src="https://github.com/user-attachments/assets/2703cb15-0be6-4df5-9c79-a45ac514444e"
/>
<img width="1192" height="750" alt="Screenshot 2026-01-09 at 1 49 01 PM"
src="https://github.com/user-attachments/assets/9cfd4936-ed2f-4e4d-a5f9-0c25c87623f1"
/>
<!
--
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**
* Manage and set default payment methods (user & team) via Setup
Intents; Payments page in Account Settings to view/update card and
active plans.
* Product listings now include type (one_time | subscription) and
subscription details (period end, cancelable, cancel-at-period-end).
* Client/SDK: new billing APIs and Customer methods to fetch billing,
create setup intents, and apply default payment methods.
* **Tests**
* New end-to-end tests for billing flows, setup-intent, and access
control.
* **Chores**
* Added Stripe frontend libraries.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- restricted users
- onboarding app
- waitlist app
- fixed an exception when setting primary email
- automatically update the JWT token on the client when the user object
changes
<img width="1299" height="967" alt="Screenshot 2025-12-12 at 5 26 23 PM"
src="https://github.com/user-attachments/assets/5a33482a-510c-464c-a770-e71222ffc336"
/>
<!--
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**
* Added a "Payouts" section to the Payments dashboard with a dedicated
page and navigation link.
* Integrated a Stripe Connect payouts UI, allowing users to manage and
configure payout options (instant payouts, standard payouts, edit payout
schedule, external account collection).
* **Chores**
* Internal module path updates (no user-facing behavior changes).
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
