cms.fellies.org/docs/product-engineering/auth-baseline.md

Better Auth Baseline

Scope

This baseline activates Better Auth for the admin app with email/password login and Prisma-backed sessions.

Implemented in MVP0:

• Admin-local auth config: apps/admin/src/lib/auth/server.ts
• Admin auth API routes: apps/admin/src/app/api/auth/[...all]/route.ts
• Admin auth pages: /welcome, /login, /register
• Support fallback sign-in page: /support/<CMS_SUPPORT_LOGIN_KEY>
• Prisma auth models (user, session, account, verification)
• First registration creates owner; subsequent registrations are disabled
• Owner invariant reconciliation is enforced in auth bootstrap and owner promotion flow
• Protected accounts (support + canonical owner) are blocked from delete-account auth endpoints

Environment

Required variables:

• BETTER_AUTH_SECRET
• BETTER_AUTH_URL
• CMS_ADMIN_ORIGIN
• CMS_WEB_ORIGIN
• DATABASE_URL

Optional:

• CMS_ADMIN_SELF_REGISTRATION_ENABLED
• CMS_SUPPORT_USERNAME
• CMS_SUPPORT_EMAIL
• CMS_SUPPORT_PASSWORD
• CMS_SUPPORT_NAME
• CMS_SUPPORT_LOGIN_KEY
• CMS_DEV_ROLE (development-only middleware bypass)

Notes

• Support user bootstrap is available via bun run auth:seed:support.
• Root bun run db:seed runs DB seed and support-user seed.
• CMS_ADMIN_SELF_REGISTRATION_ENABLED is now a fallback/default only.
• Runtime source of truth is admin settings (/settings) backed by system_setting.
• Owner/support checks for future admin user-management mutations remain tracked in TODO.md.
• Email verification and forgot/reset password pipelines are tracked for MVP2.