feat(platform): replace Supabase Auth with Better Auth

[ntindle]

Why / What / How

Why: The platform's only hard dependency on the Supabase stack was auth (GoTrue + Kong + the auth.users schema). That dependency forced every deployment — including local/self-hosted — to run the full docker-compose Supabase sidecar, which blocks the longer-term goal of shipping the platform as a single container or packaged app.

What: Replaces Supabase Auth with Better Auth (1.6.x) embedded in the Next.js frontend, with zero session loss for existing users and zero password resets.

How:

• Auth service lives in the Next.js server at /api/auth/* (cookie-based DB sessions, tables in the platform schema of the existing Postgres, owned by Prisma migrations — one migration authority).
• Backend validation: the JWT plugin signs ES256 tokens published at /api/auth/jwks; autogpt_libs.auth now validates asymmetric tokens against JWT_JWKS_URL while keeping the legacy HS256 shared-secret path active, dispatched by token algorithm. JWT claims are shaped identically to GoTrue's (sub, email, role, user_metadata.name, aud: "authenticated"), so no route/handler changes were needed.
• No session loss: three mechanisms layered —
  1. backend dual-validation keeps in-flight legacy JWTs working,
  2. a supabase-bridge Better Auth plugin silently upgrades a legacy Supabase cookie (signature-verified, accepted up to SUPABASE_BRIDGE_MAX_TOKEN_AGE_DAYS past expiry since refresh tokens have no issuer anymore) into a Better Auth session, triggered by middleware exactly once per browser,
  3. scripts/migrate-supabase-auth.ts copies auth.users/auth.identities into the Better Auth tables preserving UUIDs (no FK orphans) and bcrypt hashes (Better Auth is configured with bcrypt hashing, so GoTrue passwords keep verifying).
• Token plumbing: browser API calls already go through /api/proxy, so backend JWTs are minted server-side from the cookie session (with a per-session mint cache) — the browser never holds a JWT.
• Compose: kong, auth (GoTrue), studio, meta removed; db is now plain pgvector/pgvector:pg16 with an init shim that creates a minimal auth.users so the historical migration chain applies on fresh databases.

Changes 🏗️

• autogpt_libs.auth: JWKS (ES256/RS256/EdDSA) validation via JWT_JWKS_URL + legacy JWT_VERIFY_KEY HS256 path; config validation requires at least one
• Prisma: Better Auth tables (UserAuthIdentity, UserAuthSession, UserAuthAccount, UserAuthVerification, UserAuthJwks) + migration that also drops the auth.users sync trigger
• Backend: removed supabase SDK; feature-flag LD context now reads the auth user table; e2e test data seeds bcrypt credential accounts
• Frontend: new src/lib/auth module (server config w/ admin+jwt+bridge plugins, actions, hooks, middleware); all ~50 useSupabase consumers migrated to useAuth (same surface); login/signup/OAuth/password-reset/email-change flows rewritten; @supabase/* packages removed
• Infra: compose without the Supabase stack; CI provisions plain pgvector Postgres; env defaults updated (see below); installer + docs updated
• kysely pinned to 0.28.17 (upstream @better-auth/kysely-adapter imports a constant kysely 0.29 removed from the root export)

Configuration changes:

• Backend: +JWT_JWKS_URL, SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY removed, JWT_VERIFY_KEY retained for the migration window
• Frontend: +BETTER_AUTH_SECRET, +BETTER_AUTH_URL, +DATABASE_URL, +AUTH_DB_SCHEMA, optional AUTH_{GOOGLE,GITHUB,DISCORD}_CLIENT_ID/SECRET, optional SMTP_*, optional SUPABASE_JWT_SECRET (bridge window only); NEXT_PUBLIC_SUPABASE_* removed
• OAuth provider consoles need redirect URIs updated from GoTrue (/auth/v1/callback) to https://<frontend>/api/auth/callback/{provider}

Cloud rollout order (automated on merge): the deploy workflow's migrate job runs the schema migrations including the bulk GoTrue→Better Auth copy (20260716120000_copy_supabase_users_to_better_auth), and the backend deploy dispatches only after it succeeds. The Vercel frontend build runs in parallel off the same push — if it finishes first, auth 500s briefly until the migrate job lands (self-heals; no action needed). After the frontend flip, run the “AutoGPT Platform - Supabase Auth Sweep” workflow (workflow_dispatch, environment picker) once to copy any users who signed up via GoTrue in between. Keep SUPABASE_JWT_SECRET set (JWT_VERIFY_KEY falls back to it) through the bridge window → after the window, drop the legacy secrets and the GoTrue infra.

Checklist 📋

For code changes:

• I have clearly listed my changes in the PR description
• I have made a test plan
• I have tested my changes according to the test plan:
  • Fresh plain-Postgres DB: full Prisma migration chain applies (auth shim verified)
  • Signup via Better Auth → UUID user + session cookie; platform User created via backend with same id
  • /api/auth/jwks serves ES256 key; minted JWT carries sub/email/role/user_metadata/aud=authenticated
  • Python backend accepts the ES256 JWT via JWKS (POST /api/auth/user → 200)
  • Legacy GoTrue-style HS256 JWT still accepted by the backend (dual validation)
  • Bridge: expired-but-valid legacy sb-* cookie on a protected page → Better Auth session minted, sb cookies cleared, redirected to original destination
  • bcrypt sign-in 200, wrong password 401; protected pages redirect without session, render with one; /api/proxy mints backend JWT (credits endpoint 200)
  • Backend: 627 util tests + user-data tests green; autogpt_libs auth suite green (new JWKS tests incl. rotation/kid-miss)
  • Frontend: pnpm types/lint clean; 3215+ unit tests green incl. new bridge/middleware/mapping tests

For configuration changes:

• .env.default is updated or already compatible with my changes
• docker-compose.yml is updated or already compatible with my changes
• I have included a list of my configuration changes in the PR description (under Changes)

🤖 Generated with Claude Code

Cloud deploy checklist ☁️

Things that live outside this repo's code and must be handled at rollout (in order):

1. Waitlist: signup gating was a Postgres trigger on auth.users; new signups insert into platform."user" where no trigger exists. Port the waitlist check (trigger on platform."user" or a Better Auth databaseHooks.user.create.before hook) before deploy, or signups are open. The frontend's not_allowed error handling is preserved and ready.
2. Infra repo env/manifests: set BETTER_AUTH_SECRET (the compose default is dev-only), frontend DATABASE_URL + AUTH_DB_SCHEMA=platform, backend JWT_JWKS_URL, SMTP credentials (Postmark SMTP works; without SMTP, password reset/verification/email-change flows fail loudly by design); keep JWT_VERIFY_KEY + SUPABASE_JWT_SECRET set for the bridge window; remove GoTrue/Kong workloads after the window.
3. OAuth consoles: change Google/GitHub/Discord redirect URIs from GoTrue /auth/v1/callback to https://<frontend>/api/auth/callback/{provider}, then smoke-test each provider in staging — including a sign-in by a migrated OAuth user (identity rows are migrated and account linking is enabled, but no live provider flow runs in CI).
4. Data migration: automated — the bulk copy rides the deploy workflow's migrate job. Post-flip, run the “AutoGPT Platform - Supabase Auth Sweep” workflow once for stragglers (idempotent / re-runnable; frontend/scripts/migrate-supabase-auth.ts under the hood).
5. Known accepted trade-offs: bridge accepts signature-valid Supabase tokens ≤30 days past expiry (SUPABASE_BRIDGE_MAX_TOKEN_AGE_DAYS); open SPA tabs at cutover 401 until one page reload; migrated temporary bans become permanent; GoTrue 2FA enrollments don't migrate (no 2FA UI exists today).
6. Post-merge hardening: back Better Auth's rate limiter with Redis for multi-replica (per-instance memory by default); admin role assignment is now role='admin' on platform."user"; delete the inert db/docker/ tree in a cleanup PR.

Rollback ⏮️

Precondition — the rollback window: keep the GoTrue/Kong workloads and JWT_VERIFY_KEY + SUPABASE_JWT_SECRET running until the cutover is confirmed healthy. Dropping the legacy infra/secrets (final step of the rollout order) is the point of no return — don't do it until you're confident.

1. Roll the frontend back in Vercel — Instant Rollback to the previous deployment of the environment (or revert the merge commit on the branch). The backend needs no revert — dual-validation still accepts GoTrue HS256 tokens, and the old frontend re-issues them. (Backend JWKS fetches fail while rolled back, which is what makes already-bridged ES256 sessions 401 as described below — expected, not a fault.)
2. Sessions: anyone still holding a valid GoTrue cookie continues uninterrupted; anyone who had already bridged to a Better Auth session 401s once → one reload → re-logs-in via GoTrue (their auth.users credential still exists).
3. No DB rollback needed — leave the Better Auth tables in place; the old system ignores them.

One-way caveat: users who signed up or changed their password on Better Auth during the cutover window exist only in platform."user"/account, not auth.users, so after rollback they can't log in via GoTrue. Mitigate by picking one: (a) keep the window short and accept the few re-signups, (b) freeze new signups during the window, or (c) reverse-sync new platform."user" rows into auth.users before rolling back.

---

Note

High Risk
This is a full authentication and deployment-model change (JWT verification, session migration, CI database setup) touching security-critical paths; rollout order and env secrets (JWT_JWKS_URL, bridge window) matter for production access.

Overview
Replaces the Supabase auth stack (Kong, GoTrue, Studio, related env) with plain pgvector Postgres and Better Auth on the frontend. Platform .env.default is trimmed to database credentials; local DB data moves to data/db/data.

autogpt_libs.auth is reworked for Better Auth: JWT_JWKS_URL is required at startup (with cleartext remote http:// blocked unless JWKS_ALLOW_INSECURE_TRANSPORT). Tokens verify via JWKS (ES256, etc.) or legacy HS256 (JWT_VERIFY_KEY / SUPABASE_JWT_SECRET) by algorithm. New requires_frontend_service guards pre-login backend calls with JWKS-signed service tokens (separate audience from user JWTs). Missing role claims fail closed (403 admin, default "user" elsewhere) instead of KeyError/500.

CI and workflows: Docker image caches swap Supabase images for pgvector/pgvector:pg15; backend tests use a pgvector container + init shim instead of supabase start; pytest drops SUPABASE_* env; new autogpt-libs-test job. Full-stack E2E starts db only (no GoTrue), caches/dumps platform schema (Better Auth tables), and fails if rest_server is unhealthy after 180s. Adds manual “Supabase Auth Sweep” workflow running migrate-supabase-auth.ts post-cutover.

Also: SECURITY.md clarifies JWKS transport warnings are operator guidance; .gitignore for supabase/.temp/; removal of supabase_integration_credentials_store/types.py from the diff hunk.

^{Reviewed by Cursor Bugbot for commit ffc0264. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The PR migrates platform authentication from Supabase to Better Auth, adds JWKS-based JWT verification and service-token authorization, introduces transactional auth-email delivery, replaces the local Supabase stack with PostgreSQL/pgvector, adds user migration paths, and updates frontend consumers, CI, tests, configuration, and documentation.

Changes

Better Auth foundation

Layer / File(s)	Summary
JWT, session, and service-token foundation autogpt_platform/autogpt_libs/..., autogpt_platform/frontend/src/lib/auth/*	Adds Better Auth sessions, mapped user types, JWKS verification, service tokens, signup gating, legacy-session bridging, middleware, and server session helpers.
Authentication entry points and user flows autogpt_platform/frontend/src/app/**, autogpt_platform/frontend/src/middleware.ts	Migrates login, signup, OAuth, password reset, callbacks, user updates, logout, and middleware to Better Auth APIs and cookies.
Frontend auth consumers and tests autogpt_platform/frontend/src/components/**, src/providers/**, src/services/**	Replaces Supabase hooks, mocks, and user types with useAuth, Better Auth actions, and local auth types.

Backend and database integration

Layer / File(s)	Summary
Transactional email API autogpt_platform/backend/backend/api/features/auth_email/*, backend/notifications/*	Adds a service-token-protected email endpoint that validates action links and delegates delivery through the notification manager and Postmark sender.
Better Auth persistence and migration backend/schema.prisma, backend/migrations/*, db/init/*, frontend/scripts/*	Adds Better Auth tables, indexes, legacy cleanup, conflict-safe SQL migration, and batched user migration tooling.
PostgreSQL/pgvector runtime and CI docker-compose*.yml, .github/workflows/*	Starts PostgreSQL/pgvector locally and in CI, seeds Better Auth users, updates database URLs, and restores platform-only E2E data.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• Significant-Gravitas/AutoGPT#12123: Related password-reset and expired-link handling.
• Significant-Gravitas/AutoGPT#12437: Related fullstack CI and E2E workflow changes.
• Significant-Gravitas/AutoGPT#12960: Related frontend middleware and middleware-test changes.

Suggested labels: Possible security concern, Review effort 5/5

Suggested reviewers: bentlybro, pwuts, kcze

Poem

I’m a bunny with keys in a brand-new nest,
JWKS and carrots secure every request.
Postgres hums softly, auth gates glow,
Better Auth blooms as old services depart.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.10% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: replacing Supabase Auth with Better Auth.
Description check	✅ Passed	The description is detailed and directly matches the auth migration, infra, and rollout changes in the PR.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch better-auth-migration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 87.76529% with 98 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.90%. Comparing base (9d30196) to head (ffc0264).

Additional details and impacted files

@@            Coverage Diff             @@
##              dev   #13330      +/-   ##
==========================================
+ Coverage   76.77%   76.90%   +0.13%     
==========================================
  Files        2750     2761      +11     
  Lines      209139   209516     +377     
  Branches    20059    20078      +19     
==========================================
+ Hits       160559   161131     +572     
+ Misses      44198    43946     -252     
- Partials     4382     4439      +57     

Flag	Coverage Δ
platform-backend	83.33% <96.12%> (+0.02%)	⬆️
platform-frontend	49.15% <81.22%> (+0.82%)	⬆️
platform-frontend-e2e	30.88% <50.00%> (-0.25%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
Platform Backend	83.33% <96.12%> (+0.02%)	⬆️
Platform Frontend	52.67% <82.48%> (+0.69%)	⬆️
AutoGPT Libs	∅ <ø> (∅)
Classic AutoGPT	28.43% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🧹 Auto-undeploying: PR closed with active deployment. Cleaning up development environment for PR #13330.

[Pwuts]

🧹 Preview Environment Cleaned Up

All resources for PR #13330 have been removed:

• ☸️ Kubernetes namespace deleted
• 🗃️ Preview branch database deleted

Cleanup completed successfully.