import { betterAuth } from 'better-auth'; import { drizzleAdapter } from 'better-auth/adapters/drizzle'; import { APIError, createAuthMiddleware } from 'better-auth/api'; import { admin, magicLink, twoFactor } from 'better-auth/plugins'; import { createAccessControl } from 'better-auth/plugins/access'; import { adminAc, defaultStatements, userAc } from 'better-auth/plugins/admin/access'; import { adminDb } from '../db/client'; import * as schema from '../db/schema'; import { isEmailConfigured } from '../lib/email'; import { env } from '../lib/env'; import { allowedOrigins } from '../lib/origins'; import { refuseCredentialUnlinkRow, rejectOrphanedPasswordSession, secureSocialLink, sweepUnprovenSecondFactor, } from './account-linking'; import { sessionAssurance } from './assurance'; import { magicLinkAvailable, sendAuthEmail } from './email'; import { capImpersonationExpiry, impersonationGuard } from './impersonation'; import { lockoutPlugin } from './lockout'; import { socialProviders } from './providers'; import { recordSignIn } from './sign-in-record'; import { stripSessionToken } from './strip-session-token'; /** * The app's one auth instance, mounted at /api/auth/* (server/index.ts). * * - Postgres through Drizzle on `adminDb`: the auth tables have no app_user * privileges, so Better Auth must bypass RLS. Ids are uuids the database * generates (`generateId: false`), so every `uuid` foreign key to "user" * keeps working. * - Sessions are HttpOnly cookies (SameSite=Lax, Secure on https). The * session middleware reads them with `auth.api.getSession`. * - Super admin is `user.role = 'super_admin'` (admin plugin). There is no * platform `admin` role, and no endpoint assigns roles: the super_admin * role lacks `set-role` and the set-role path is disabled. The only way to * a super admin is the startup bootstrap (auth/bootstrap-admin.ts). * - Email + password sign-in goes through the account lockout hooks. * - Two-factor (TOTP + backup codes) and the per-session assurance level * (aal2 = this session passed a second factor): auth/assurance.ts. */ const ac = createAccessControl(defaultStatements); /** * Everything the stock admin role may do except assign roles. Impersonating * another admin (`impersonate-admins`) is not granted either. */ const superAdminRole = ac.newRole({ user: adminAc.statements.user.filter((action) => action !== 'set-role'), session: [...adminAc.statements.session], }); /** Verification emails are required only when they can actually be sent. */ const emailConfigured = isEmailConfigured(); export const auth = betterAuth({ appName: '{{PROJECT_DISPLAY_NAME}}', basePath: '/api/auth', // Always SITE_URL (required by env.ts): emailed links and OAuth callbacks // never take their origin from the request's Host header. baseURL: env.SITE_URL, secret: env.BETTER_AUTH_SECRET, // The same list CORS and the CSRF check use (lib/origins.ts): SITE_URL, // CORS_ORIGINS, and the local dev ports outside production. Better Auth // also accepts these as callback/redirect targets. trustedOrigins: allowedOrigins(), database: drizzleAdapter(adminDb, { provider: 'pg', schema }), advanced: { database: { generateId: false }, // Explicit, so the origin and CSRF checks also run under NODE_ENV=test // (Better Auth skips them there by default) and tests see production. disableOriginCheck: false, disableCSRFCheck: false, }, // Our own limiter covers /api/auth (server/index.ts) and reads the client // IP the trusted-proxy way; Better Auth's reads X-Forwarded-For as given. rateLimit: { enabled: false }, session: { // Short: the app's API session middleware never reads it (it always reads // the database), and Better Auth's admin endpoints bypass it, so a revoked // session lingers for at most a minute in its own get-session answers. cookieCache: { enabled: true, maxAge: 60 }, additionalFields: { // Set only by the second-factor verify hook (auth/assurance.ts). Never // client input: /update-session refuses it (and is disabled below). twoFactorVerified: { type: 'boolean', defaultValue: false, required: false, input: false }, }, }, user: { additionalFields: { onboardingCompleted: { type: 'boolean', defaultValue: false, required: false, input: true, }, }, }, emailAndPassword: { enabled: true, minPasswordLength: 8, requireEmailVerification: emailConfigured, resetPasswordTokenExpiresIn: 60 * 60, // A reset is how an owner takes a compromised account back, so every // session issued on the old password ends with it, the attacker's too. revokeSessionsOnPasswordReset: true, sendResetPassword: async ({ user, url }) => { await sendAuthEmail('password reset', user.email, url); }, }, emailVerification: { sendOnSignUp: emailConfigured, autoSignInAfterVerification: true, sendVerificationEmail: async ({ user, url }) => { await sendAuthEmail('verification', user.email, url); }, }, account: { accountLinking: { enabled: true, // No provider is trusted by name: a social sign-in links onto an // existing account by email only when the provider says the email is // verified. Local verification is not required (without SMTP nobody // could verify), because secureSocialLink below removes any password // set on an unverified address when such a link happens. trustedProviders: [], requireLocalEmailVerified: false, allowDifferentEmails: false, }, }, databaseHooks: { session: { create: { // The other half of the pre-hijacking defence: a password sign-in // that raced the cleanup gets no session (auth/account-linking.ts). after: async (created, ctx) => { // The session this one replaces, when the endpoint had one. const source = (ctx?.context as { session?: { session?: { id?: string } } | null }) ?.session?.session?.id; await rejectOrphanedPasswordSession(created, ctx?.path, source); await recordSignIn(created); }, }, update: { // An impersonation session never outlives its hour // (auth/impersonation.ts). before: async (update, ctx) => capImpersonationExpiry(update, ctx), }, }, user: { update: { // A magic link that proves an unverified address drops any second // factor enrolled on it. The fail-closed pass runs before the link // is used (auth/assurance.ts); this is the best-effort second pass // (auth/account-linking.ts, dropUnprovenSecondFactor). after: async (updated, ctx) => { await sweepUnprovenSecondFactor(updated, ctx?.path); }, }, }, account: { create: { // Pre-hijacking defence (auth/account-linking.ts). A before hook, so // the cleanup commits before the link is written, and a failure // (thrown) stops the link: fail closed. before: async (linking) => { await secureSocialLink(linking); }, }, delete: { // The password cannot be unlinked (also refused at the endpoint, // auth/assurance.ts); see auth/account-linking.ts. before: async (deleting, ctx) => { refuseCredentialUnlinkRow(deleting, ctx?.path); }, }, }, }, socialProviders: { ...(socialProviders.google ? { google: { clientId: env.GOOGLE_CLIENT_ID as string, clientSecret: env.GOOGLE_CLIENT_SECRET as string, }, } : {}), ...(socialProviders.microsoft ? { microsoft: { clientId: env.MICROSOFT_CLIENT_ID as string, clientSecret: env.MICROSOFT_CLIENT_SECRET as string, tenantId: env.MICROSOFT_TENANT_ID || 'common', }, } : {}), }, // Paths not served over HTTP. Server-side `auth.api.*` calls still reach // them (the startup bootstrap uses createUser). disabledPaths: [ // Admin endpoints the app does not use. Only impersonate-user and // stop-impersonating stay (the admin users page; rules in // auth/impersonation.ts). The users list, stats and account deletion // are app routes over the database (routes/v1). set-role must never be // reachable: role assignment is bootstrap-only. '/admin/set-role', '/admin/list-users', '/admin/remove-user', '/admin/create-user', '/admin/update-user', '/admin/get-user', '/admin/set-user-password', '/admin/ban-user', '/admin/unban-user', '/admin/list-user-sessions', '/admin/revoke-user-session', '/admin/revoke-user-sessions', '/admin/has-permission', // Its only use is writing session fields, and the one session field // (twoFactorVerified) is server-only. '/update-session', // Second factor by emailed one-time code: not offered (TOTP and backup // codes only), so its send and verify paths stay closed. '/two-factor/send-otp', '/two-factor/verify-otp', ...(env.MAGIC_LINK_ENABLED ? [] : ['/sign-in/magic-link', '/magic-link/verify']), ], // Runs before every endpoint (and before the plugins' own hooks). A // sign-in link with no SMTP to deliver it would leave the user waiting // for an email that never comes, so the send is refused with a code the // client can show; the settings route stops offering it too. hooks: { before: createAuthMiddleware(async (ctx) => { if (ctx.path === '/sign-in/magic-link' && !magicLinkAvailable()) { throw new APIError('BAD_REQUEST', { code: 'MAGIC_LINK_UNAVAILABLE', message: 'Sign-in links need email, and this app has no email server set up. Sign in with your password instead.', }); } }), }, // ORDER MATTERS. After hooks run in this order, and each later plugin sees // what the earlier ones returned: // admin, magicLink, twoFactor, sessionAssurance, impersonationGuard, // lockout, stripSessionToken. // lockout must follow twoFactor (a pending 2FA challenge is neither a // failure nor a success); sessionAssurance must follow twoFactor (it marks // the session a verify endpoint produced); stripSessionToken must be last // (it rewrites every body the others produced). plugins: [ admin({ ac, roles: { super_admin: superAdminRole, user: userAc }, adminRoles: ['super_admin'], defaultRole: 'user', }), // Always registered so the API types stay fixed; MAGIC_LINK_ENABLED=false // disables its paths above. magicLink({ expiresIn: 5 * 60, sendMagicLink: async ({ email, url }) => { await sendAuthEmail('magic link', email, url); }, }), // TOTP (authenticator app) with backup codes. A password sign-in by a // user with 2FA enabled stops at a challenge until a code is verified. // Magic link and social sign-in are not challenged; those sessions stay // aal1 until a code is verified from them (step-up, auth/assurance.ts). twoFactor({ issuer: '{{PROJECT_DISPLAY_NAME}}', // An account without a password (social or magic link only) can still // enroll and remove 2FA; a password account must give its password. // The session checks in auth/assurance.ts and auth/account-linking.ts // stand in for the password there. allowPasswordless: true, }), sessionAssurance(), // After sessionAssurance: an aal1 admin hears "verify a code" first. impersonationGuard(), lockoutPlugin(), // Last, so it sees every other plugin's response: no session token in // any JSON body; the HttpOnly cookie is its only carrier. stripSessionToken(), ], }); export type AuthSessionData = typeof auth.$Infer.Session; export type AuthUser = AuthSessionData['user']; export type AuthSession = AuthSessionData['session'];