From a45776ecb97a35db8afb0cc107401f65c9ecaea7 Mon Sep 17 00:00:00 2001
From: Danny White <3104761+dnywh@users.noreply.github.com>
Date: Thu, 28 May 2026 15:23:45 +1000
Subject: [PATCH] feat(studio): restrict auth email template editing for free
projects (#45396)
## What kind of change does this PR introduce?
Feature / abuse-prevention update. Resolves DEPR-198.
## What is the current behaviour?
Free projects using Supabase's built-in email service can edit raw Auth
email template subjects and HTML in Studio. That is the risky cohort
this project is trying to constrain.
## What is the new behaviour?
### Template editing restrictions
For free projects using Supabase's built-in email service, Studio keeps
Auth email templates viewable and previewable but disables subject/body
editing and saving. Editing is unlocked by setting up Custom SMTP,
configuring a send-email hook, or upgrading to a paid plan.
**Grandfathering:** projects created before `2026-06-01T00:00:00Z` (the
platform enforcement cutoff) are exempt; their editing UI stays
unlocked. This mirrors `FREE_TIER_TEMPLATE_BLOCK_CUTOFF_DATE` in the
platform PR exactly.
| After |
| --- |
| |
| |
### Warning dialogs on transitions that reset templates
Two flows now surface a warning before the user commits to a state
change that resets their custom email templates to defaults:
1. **Disabling custom SMTP** (SMTP settings page): a confirmation dialog
warns that templates will be reset to defaults and the email rate limit
reduced to 2 per hour. On confirm, Studio resets all 13 templates via
the existing per-template reset endpoint (`Promise.allSettled`). The
"won't be able to edit" sentence is shown only for post-cutoff projects;
grandfathered projects skip it. The corresponding server-side
enforcement is in the Platform PR:
https://github.com/supabase/platform/pull/33129
2. **Downgrading to the Free plan** (billing settings): an admonition in
the existing downgrade confirmation modal warns that custom templates
will be reset to defaults and won't be editable without custom SMTP. The
admonition is shown only when the org has at least one post-cutoff
project; orgs whose projects are all grandfathered skip it.
| Custom SMTP | Downgrading |
| --- | --- |
| | |
### Informational admonition when enabling SMTP
When a user enables custom SMTP for the first time, a sandwiched
admonition above the save footer informs them that the email rate limit
will be increased to 30 per hour and can be adjusted.
_This is just a minor cosmetic change, unrelated to the email template
disabling. Sorry._
| Before | After |
| --- | --- |
| | |
## How to test
All existing projects pre-date the enforcement cutoff
(`2026-06-01T00:00:00Z`) and are grandfathered, so the restriction UI
won't appear by default. To force the restricted state locally,
back-date the cutoff in one file:
In
`apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.utils.ts`,
temporarily change:
```ts
export const FREE_TIER_TEMPLATE_BLOCK_CUTOFF_DATE = '2026-06-01T00:00:00Z'
```
to:
```ts
export const FREE_TIER_TEMPLATE_BLOCK_CUTOFF_DATE = '2025-01-01T00:00:00Z'
```
Revert before committing. With the cutoff back-dated, use a free-plan
project and:
- **Template restriction + admonition:** navigate to Authentication >
Emails with no custom SMTP configured. Subject/body fields should be
read-only and the "Set up SMTP" admonition should appear, with its
dropdown offering upgrade and send-email hook options.
- **SMTP disable warning:** enable custom SMTP on a project, then
disable it via Authentication > SMTP Settings. The confirmation dialog
should warn that templates will reset to defaults and that editing will
be restricted after disabling.
- **Downgrade warning:** in billing settings, initiate a downgrade to
the Free plan. The downgrade modal should include an admonition warning
about template reset and restricted editing (only if the org has at
least one post-cutoff project).
## Additional context
The default Auth email template copy was also improved across docs,
examples, and UI library snippets (separate prior commits).
The per-template reset button (`ResetTemplateDialog`) was migrated to
the async `AlertDialogAction` pattern introduced in #45960; the dialog
stays open and shows a loading state while the reset is in-flight,
closes on success, and stays open on error.
Closes PRODSEC-183
---------
Co-authored-by: Joshen Lim
Co-authored-by: Claude Sonnet 4.5
Co-authored-by: Stephen Morgan
---
.../guides/auth/auth-email-passwordless.mdx | 6 +-
.../getting-started/tutorials/with-nextjs.mdx | 2 +-
.../self-hosting/custom-email-templates.mdx | 2 +-
...stomEmailTemplateRestrictionAdmonition.tsx | 73 ++++++++
.../EmailTemplates.constants.ts | 5 +
.../Auth/EmailTemplates/EmailTemplates.tsx | 39 +++-
.../EmailTemplates/EmailTemplates.types.ts | 2 +-
.../EmailTemplates.utils.test.ts | 137 ++++++++++++++
.../EmailTemplates/EmailTemplates.utils.ts | 58 ++++++
.../EmailTemplates/ResetTemplateDialog.tsx | 31 ++--
.../EmailTemplates/TemplateEditor.test.tsx | 5 +-
.../Auth/EmailTemplates/TemplateEditor.tsx | 82 +++++++--
.../SmtpDisableConfirmationDialog.tsx | 58 ++++++
.../interfaces/Auth/SmtpForm/SmtpForm.tsx | 173 ++++++++++++------
.../Auth/SmtpForm/SmtpForm.utils.ts | 1 +
.../Subscription/DowngradeModal.tsx | 20 +-
.../Subscription/PlanUpdateSidePanel.test.tsx | 2 +-
.../Subscription/PlanUpdateSidePanel.tsx | 2 +-
apps/studio/components/ui/TwoOptionToggle.tsx | 55 ++++--
.../[ref]/auth/templates/[templateId].tsx | 31 +++-
.../supabase/templates/confirmation.html | 6 +-
.../supabase/templates/recovery.html | 6 +-
.../supabase/auth/email/magic-link.html | 6 +-
.../supabase/config.toml | 4 +-
24 files changed, 665 insertions(+), 141 deletions(-)
create mode 100644 apps/studio/components/interfaces/Auth/EmailTemplates/CustomEmailTemplateRestrictionAdmonition.tsx
create mode 100644 apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.constants.ts
create mode 100644 apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.utils.test.ts
create mode 100644 apps/studio/components/interfaces/Auth/SmtpForm/SmtpDisableConfirmationDialog.tsx
diff --git a/apps/docs/content/guides/auth/auth-email-passwordless.mdx b/apps/docs/content/guides/auth/auth-email-passwordless.mdx
index b98a1f43a0f..647211150ba 100644
--- a/apps/docs/content/guides/auth/auth-email-passwordless.mdx
+++ b/apps/docs/content/guides/auth/auth-email-passwordless.mdx
@@ -145,10 +145,10 @@ That's it for the implicit flow.
If you're using PKCE flow, edit the Magic Link [email template](/docs/guides/auth/auth-email-templates) to send a token hash:
```html
-
```
At the `/auth/confirm` endpoint, exchange the hash for the session:
diff --git a/apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx b/apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx
index 82e348a086d..f7fd26e7894 100644
--- a/apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx
+++ b/apps/docs/content/guides/getting-started/tutorials/with-nextjs.mdx
@@ -268,7 +268,7 @@ npm run dev
And then open the browser to [localhost:3000/login](http://localhost:3000/login) and you should see the completed app.
-When you enter your email and password, you will receive an email with the title **Confirm Your Signup**. Congrats 🎉!!!
+When you enter your email and password, you will receive an email with the title **Confirm your email**. Congrats 🎉!!!
At this stage you have a fully functional application!
diff --git a/apps/docs/content/guides/self-hosting/custom-email-templates.mdx b/apps/docs/content/guides/self-hosting/custom-email-templates.mdx
index 090dfc390c3..694ab393496 100644
--- a/apps/docs/content/guides/self-hosting/custom-email-templates.mdx
+++ b/apps/docs/content/guides/self-hosting/custom-email-templates.mdx
@@ -159,7 +159,7 @@ services:
environment:
GOTRUE_MAILER_NOTIFICATIONS_PASSWORD_CHANGED_ENABLED: 'true' # 👈 enabling the notification is required
GOTRUE_MAILER_TEMPLATES_PASSWORD_CHANGED_NOTIFICATION: 'http://templates-server/password_changed_notification.html'
- GOTRUE_MAILER_SUBJECTS_PASSWORD_CHANGED_NOTIFICATION: 'Your password has been changed'
+ GOTRUE_MAILER_SUBJECTS_PASSWORD_CHANGED_NOTIFICATION: 'Your password was changed'
templates-server:
image: caddy:2-alpine
diff --git a/apps/studio/components/interfaces/Auth/EmailTemplates/CustomEmailTemplateRestrictionAdmonition.tsx b/apps/studio/components/interfaces/Auth/EmailTemplates/CustomEmailTemplateRestrictionAdmonition.tsx
new file mode 100644
index 00000000000..1ac63e3accc
--- /dev/null
+++ b/apps/studio/components/interfaces/Auth/EmailTemplates/CustomEmailTemplateRestrictionAdmonition.tsx
@@ -0,0 +1,73 @@
+import { useParams } from 'common'
+import { ChevronDown } from 'lucide-react'
+import Link from 'next/link'
+import {
+ Button,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from 'ui'
+import { Admonition } from 'ui-patterns/admonition'
+
+import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
+
+export const CustomEmailTemplateRestrictionAdmonition = () => {
+ const { ref: projectRef } = useParams()
+ const { data: selectedOrganization } = useSelectedOrganizationQuery()
+ const organizationSlug = selectedOrganization?.slug ?? '_'
+
+ return (
+
+
+
+
+ }
+ />
+
+
+
+
+
+
Upgrade to Pro
+
+ Customize templates while using Supabase’s email service
+