@opensaas/stack-auth 0.35.0 → 0.37.0

package/src/server/index.ts

@@ -34,6 +34,240 @@ function toBetterAuthModelOptions(
   return Object.keys(options).length > 0 ? options : undefined
 }
 
+const MODELS_WITH_NO_ADDITIONAL_FIELDS_PASSTHROUGH = [
+  'user',
+  'session',
+  'account',
+  'verification',
+] as const
+
+/**
+ * Reject `betterAuthOptions` keys that already have a dedicated, non-passthrough
+ * seam — accepting them here would create two unranked ways to set the same
+ * thing, or (for `additionalFields`) silently diverge from the generated
+ * Prisma schema. See the `betterAuthOptions` doc comment on `AuthConfig`.
+ */
+function assertNoUnsupportedPassthroughKeys(betterAuthOptions: Record<string, unknown>): void {
+  if ('database' in betterAuthOptions) {
+    throw new Error(
+      '[@opensaas/stack-auth] `betterAuthOptions.database` is not supported — the stack ' +
+        'derives the database adapter from your `db` config and the running context. ' +
+        'Configure the database through `db` in `opensaas.config.ts` instead.',
+    )
+  }
+
+  if ('plugins' in betterAuthOptions) {
+    throw new Error(
+      '[@opensaas/stack-auth] `betterAuthOptions.plugins` is not supported — better-auth ' +
+        'plugins are added through `authPlugin({ betterAuthPlugins: [...] })`, which the stack ' +
+        'appends `nextCookies()` after. Use `betterAuthPlugins` instead.',
+    )
+  }
+
+  for (const model of MODELS_WITH_NO_ADDITIONAL_FIELDS_PASSTHROUGH) {
+    const modelOptions = betterAuthOptions[model]
+    if (
+      modelOptions &&
+      typeof modelOptions === 'object' &&
+      !Array.isArray(modelOptions) &&
+      'additionalFields' in modelOptions
+    ) {
+      throw new Error(
+        `[@opensaas/stack-auth] \`betterAuthOptions.${model}.additionalFields\` is not ` +
+          'supported — it adds columns that would not be reflected in the generated Prisma ' +
+          'schema. Add fields to the derived list instead: ' +
+          (model === 'user'
+            ? '`extendUserList`, or declare the list yourself in your own `lists` config.'
+            : 'declare the derived list yourself in your own `lists` config (the auth plugin ' +
+              'merges in field additions for the models it derives).'),
+      )
+    }
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  )
+}
+
+/**
+ * Deep-merge `overrides` onto `base`, recursing into plain-object values so a
+ * nested addition (one database hook, one session sub-option) merges
+ * alongside sibling keys the stack already set there rather than replacing
+ * the whole branch. Arrays and any other value type replace outright.
+ * `overrides` wins on every key collision.
+ */
+function mergeBetterAuthOptions(
+  base: Record<string, unknown>,
+  overrides: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(overrides)) {
+    const baseValue = result[key]
+    result[key] =
+      isPlainObject(baseValue) && isPlainObject(value)
+        ? mergeBetterAuthOptions(baseValue, value)
+        : value
+  }
+  return result
+}
+
+/**
+ * Build the `BetterAuthOptions` a better-auth instance for this OpenSaas
+ * config should be constructed with — the same options `createAuth()` uses
+ * internally, available standalone for an app that still needs to hand-wire
+ * its own `betterAuth()` instance (e.g. a third-party contract that requires
+ * a resolved instance at module-init time). Keeps the auth plugin
+ * authoritative for everything it models; the app's additions on top become
+ * an explicit, reviewable diff instead of a parallel, hand-duplicated config.
+ *
+ * @example
+ * ```typescript
+ * import { betterAuth } from 'better-auth'
+ * import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
+ *
+ * export const auth = betterAuth({
+ *   ...(await buildBetterAuthOptions(config, context)),
+ *   databaseHooks: { user: { create: { after: syncDomainUser } } },
+ * })
+ * ```
+ */
+export async function buildBetterAuthOptions(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+): Promise<BetterAuthOptions> {
+  const resolvedConfig = await Promise.resolve(opensaasConfig)
+  const resolvedContext = await Promise.resolve(context)
+
+  // Extract auth config from plugin data
+  const authConfig = resolvedConfig._pluginData?.auth as NormalizedAuthConfig | undefined
+
+  if (!authConfig) {
+    throw new Error(
+      'Auth config not found. Make sure to use authPlugin() in your opensaas.config.ts',
+    )
+  }
+
+  // `requireConfirmation` has no better-auth equivalent — it's a UI-only
+  // concern the pre-built forms already take as their own
+  // `requirePasswordConfirmation` prop. Warn rather than silently drop it,
+  // since setting it here looks like it should do something.
+  if (
+    authConfig.emailAndPassword.enabled &&
+    authConfig.emailAndPassword.requireConfirmation !== true
+  ) {
+    console.warn(
+      '[@opensaas/stack-auth] `emailAndPassword.requireConfirmation` has no effect here — ' +
+        'createAuth() has no better-auth option to forward it to. Pass ' +
+        '`requirePasswordConfirmation` directly to <SignUpForm> / <ResetPasswordForm> instead.',
+    )
+  }
+
+  // `passwordReset` is wired through better-auth's `emailAndPassword` config
+  // (there's no password to reset without a password-based account), so it
+  // silently has no effect if email/password auth itself isn't enabled.
+  if (authConfig.passwordReset.enabled && !authConfig.emailAndPassword.enabled) {
+    console.warn(
+      '[@opensaas/stack-auth] `passwordReset.enabled` has no effect here — ' +
+        '`emailAndPassword.enabled` is false, so there is no password-based account to reset.',
+    )
+  }
+
+  assertNoUnsupportedPassthroughKeys(authConfig.betterAuthOptions as Record<string, unknown>)
+
+  // Build better-auth configuration
+  const betterAuthConfig: BetterAuthOptions = {
+    database: getDatabaseConfig(resolvedConfig.db, resolvedContext),
+
+    // Mirror the per-model config (modelName + field column maps) back to
+    // better-auth so the running auth instance reads/writes the same
+    // tables/columns the OpenSaaS Auth lists were derived from.
+    user: toBetterAuthModelOptions(authConfig.models.user),
+    session: {
+      ...toBetterAuthModelOptions(authConfig.models.session),
+      expiresIn: authConfig.session.expiresIn || 604800,
+      // better-auth treats `updateAge: 0` as "refresh on every request", not
+      // "never refresh" — disabling refresh entirely requires its separate
+      // `disableSessionRefresh` flag regardless of `updateAge`.
+      ...(authConfig.session.updateAge === false
+        ? { disableSessionRefresh: true }
+        : { updateAge: authConfig.session.updateAge }),
+    },
+    account: toBetterAuthModelOptions(authConfig.models.account),
+    verification: toBetterAuthModelOptions(authConfig.models.verification),
+
+    // Enable email and password if configured
+    emailAndPassword: authConfig.emailAndPassword.enabled
+      ? {
+          enabled: true,
+          requireEmailVerification: authConfig.emailVerification.enabled,
+          minPasswordLength: authConfig.emailAndPassword.minPasswordLength,
+          ...(authConfig.passwordReset.enabled
+            ? {
+                sendResetPassword: authConfig.emailAndPassword.sendResetPassword,
+                resetPasswordTokenExpiresIn: authConfig.passwordReset.tokenExpiration,
+              }
+            : {}),
+        }
+      : undefined,
+
+    // Email verification (independent of emailAndPassword — also covers
+    // e.g. a social-provider account whose email isn't yet verified)
+    emailVerification: authConfig.emailVerification.enabled
+      ? {
+          sendVerificationEmail: authConfig.emailVerification.sendVerificationEmail,
+          sendOnSignUp: authConfig.emailVerification.sendOnSignUp,
+          expiresIn: authConfig.emailVerification.tokenExpiration,
+        }
+      : undefined,
+
+    // Trust host (required for production)
+    trustedOrigins: process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(',') || [],
+
+    // Social providers
+    socialProviders: Object.entries(authConfig.socialProviders)
+      .filter(([_, config]) => config?.enabled !== false)
+      .reduce(
+        (acc, [provider, config]) => {
+          if (config) {
+            acc[provider] = {
+              clientId: config.clientId,
+              clientSecret: config.clientSecret,
+            }
+          }
+          return acc
+        },
+        {} as Record<string, { clientId: string; clientSecret: string }>,
+      ),
+
+    // Rate limiting configuration
+    rateLimit: authConfig.rateLimit
+      ? {
+          enabled: authConfig.rateLimit.enabled,
+          window: authConfig.rateLimit.window,
+          max: authConfig.rateLimit.max,
+        }
+      : undefined,
+
+    // Pass through any additional Better Auth plugins, then append
+    // nextCookies LAST so it can write the Set-Cookie headers produced by
+    // any auth.api.* call made inside a Next.js server action into Next's
+    // cookie store. This is what makes the server-action auth forms (which
+    // call auth.api.signInEmail/signUpEmail/etc. server-side) actually
+    // persist a session. It must be the final plugin in the array.
+    plugins: [...(authConfig.betterAuthPlugins || []), nextCookies()],
+  }
+
+  return mergeBetterAuthOptions(
+    betterAuthConfig as unknown as Record<string, unknown>,
+    authConfig.betterAuthOptions as Record<string, unknown>,
+  ) as BetterAuthOptions
+}
+
 /**
  * Create a better-auth instance from OpenSaas config
  * This should be called once at app startup
@@ -65,81 +299,7 @@ export function createAuth(
 
     if (!authPromise) {
       authPromise = (async () => {
-        const resolvedConfig = await configPromise
-        const resolvedContext = await contextPromise
-
-        // Extract auth config from plugin data
-        const authConfig = resolvedConfig._pluginData?.auth as NormalizedAuthConfig | undefined
-
-        if (!authConfig) {
-          throw new Error(
-            'Auth config not found. Make sure to use authPlugin() in your opensaas.config.ts',
-          )
-        }
-
-        // Build better-auth configuration
-        const betterAuthConfig: BetterAuthOptions = {
-          database: getDatabaseConfig(resolvedConfig.db, resolvedContext),
-
-          // Mirror the per-model config (modelName + field column maps) back to
-          // better-auth so the running auth instance reads/writes the same
-          // tables/columns the OpenSaaS Auth lists were derived from.
-          user: toBetterAuthModelOptions(authConfig.models.user),
-          session: {
-            ...toBetterAuthModelOptions(authConfig.models.session),
-            expiresIn: authConfig.session.expiresIn || 604800,
-            updateAge: authConfig.session.updateAge
-              ? (authConfig.session.expiresIn || 604800) / 10
-              : 0,
-          },
-          account: toBetterAuthModelOptions(authConfig.models.account),
-          verification: toBetterAuthModelOptions(authConfig.models.verification),
-
-          // Enable email and password if configured
-          emailAndPassword: authConfig.emailAndPassword.enabled
-            ? {
-                enabled: true,
-                requireEmailVerification: authConfig.emailVerification.enabled,
-              }
-            : undefined,
-
-          // Trust host (required for production)
-          trustedOrigins: process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(',') || [],
-
-          // Social providers
-          socialProviders: Object.entries(authConfig.socialProviders)
-            .filter(([_, config]) => config?.enabled !== false)
-            .reduce(
-              (acc, [provider, config]) => {
-                if (config) {
-                  acc[provider] = {
-                    clientId: config.clientId,
-                    clientSecret: config.clientSecret,
-                  }
-                }
-                return acc
-              },
-              {} as Record<string, { clientId: string; clientSecret: string }>,
-            ),
-
-          // Rate limiting configuration
-          rateLimit: authConfig.rateLimit
-            ? {
-                enabled: authConfig.rateLimit.enabled,
-                window: authConfig.rateLimit.window,
-                max: authConfig.rateLimit.max,
-              }
-            : undefined,
-
-          // Pass through any additional Better Auth plugins, then append
-          // nextCookies LAST so it can write the Set-Cookie headers produced by
-          // any auth.api.* call made inside a Next.js server action into Next's
-          // cookie store. This is what makes the server-action auth forms (which
-          // call auth.api.signInEmail/signUpEmail/etc. server-side) actually
-          // persist a session. It must be the final plugin in the array.
-          plugins: [...(authConfig.betterAuthPlugins || []), nextCookies()],
-        }
-
+        const betterAuthConfig = await buildBetterAuthOptions(configPromise, contextPromise)
         authInstance = betterAuth(betterAuthConfig)
         return authInstance
       })()
@@ -195,17 +355,21 @@ export function createAuth(
 }
 
 /**
- * Get session from better-auth and transform it to OpenSaas session format
- * This is used internally by the generated context
+ * Get session from better-auth and transform it to OpenSaas session format.
+ *
+ * Not called by any generated code today — apps currently hand-roll this same
+ * transform against `auth.api.getSession({ headers: await headers() })` (see
+ * `examples/starter-auth/lib/auth.ts`). Exported as a reusable helper for that
+ * pattern; pass the caller's request headers (e.g. Next.js `await headers()`
+ * in a Server Component/action) so a session cookie can actually be resolved.
  */
 export async function getSessionFromAuth(
   auth: ReturnType<typeof betterAuth>,
   sessionFields: string[],
+  headers: Headers,
 ) {
   try {
-    const session = await auth.api.getSession({
-      headers: new Headers(),
-    })
+    const session = await auth.api.getSession({ headers })
 
     if (!session?.user) {
       return null

package/tests/adopt-better-auth-tables.test.ts

@@ -76,6 +76,105 @@ describe('adoptBetterAuthTables - recipe defaults', () => {
   })
 })
 
+describe('adoptBetterAuthTables - table names (issue #862)', () => {
+  it('sets no tableName by default (prefixed modelName also pins the table, as before)', () => {
+    const fragment = adoptBetterAuthTables()
+
+    expect(fragment.user).toEqual({ modelName: 'AuthUser' })
+    expect(fragment.session).toEqual({ modelName: 'AuthSession' })
+  })
+
+  it('useBetterAuthTableNames sets every model tableName to the better-auth default lowercase name', () => {
+    const fragment = adoptBetterAuthTables({ useBetterAuthTableNames: true })
+
+    expect(fragment.user).toEqual({ modelName: 'AuthUser', tableName: 'user' })
+    expect(fragment.session).toEqual({ modelName: 'AuthSession', tableName: 'session' })
+    expect(fragment.account).toEqual({ modelName: 'AuthAccount', tableName: 'account' })
+    expect(fragment.verification).toEqual({
+      modelName: 'AuthVerification',
+      tableName: 'verification',
+    })
+  })
+
+  it('tableNames sets explicit per-model table names', () => {
+    const fragment = adoptBetterAuthTables({
+      tableNames: { user: 'users', session: 'user_sessions' },
+    })
+
+    expect(fragment.user).toEqual({ modelName: 'AuthUser', tableName: 'users' })
+    expect(fragment.session).toEqual({ modelName: 'AuthSession', tableName: 'user_sessions' })
+    // Models without an explicit tableName entry stay unset.
+    expect(fragment.account).toEqual({ modelName: 'AuthAccount' })
+  })
+
+  it('tableNames takes precedence over useBetterAuthTableNames for the same model', () => {
+    const fragment = adoptBetterAuthTables({
+      useBetterAuthTableNames: true,
+      tableNames: { user: 'custom_user_table' },
+    })
+
+    expect(fragment.user?.tableName).toBe('custom_user_table')
+    // Other models still fall back to the better-auth default.
+    expect(fragment.session?.tableName).toBe('session')
+  })
+
+  it('combines tableName with a field column map on the same model', () => {
+    const fragment = adoptBetterAuthTables({
+      useBetterAuthTableNames: true,
+      fields: { user: { name: 'full_name' } },
+    })
+
+    expect(fragment.user).toEqual({
+      modelName: 'AuthUser',
+      tableName: 'user',
+      fields: { name: 'full_name' },
+    })
+  })
+})
+
+describe('adoptBetterAuthTables - clean-diff adoption with better-auth default table names', () => {
+  it('produces Auth lists that @@map to the live lowercase tables under prefixed list keys', async () => {
+    const result = await generationConfig({
+      db: { provider: 'postgresql' },
+      plugins: [
+        authPlugin({
+          ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+          emailAndPassword: { enabled: true },
+        }),
+      ],
+      lists: {
+        User: list({
+          fields: { subjectId: text({ validation: { isRequired: true } }) },
+        }),
+      },
+    })
+
+    // List keys stay prefixed (no collision with the app's own User)...
+    expect(result.lists).toHaveProperty('AuthUser')
+    // ...but the physical table is better-auth's own default lowercase name.
+    expect(result.lists.AuthUser.db).toEqual({ timestamps: true, map: 'user', schema: 'auth' })
+    expect(result.lists.AuthSession.db).toEqual({
+      timestamps: true,
+      map: 'session',
+      schema: 'auth',
+    })
+    expect(result.lists.AuthAccount.db).toEqual({
+      timestamps: true,
+      map: 'account',
+      schema: 'auth',
+    })
+    expect(result.lists.AuthVerification.db).toEqual({
+      timestamps: true,
+      map: 'verification',
+      schema: 'auth',
+    })
+
+    // The app's own domain User is untouched.
+    expect(result.lists.User.fields).toHaveProperty('subjectId')
+    expect(result.lists.User.fields).not.toHaveProperty('email')
+  })
+})
+
 describe('adoptBetterAuthTables - composes with authPlugin', () => {
   it('spreads into authPlugin alongside the rest of the auth config', async () => {
     const result = await config({

package/tests/config.test.ts

@@ -14,9 +14,19 @@ describe('normalizeAuthConfig', () => {
     expect(result.emailVerification.enabled).toBe(false)
     expect(result.passwordReset.enabled).toBe(false)
     expect(result.session.expiresIn).toBe(604800) // 7 days
+    expect(result.session.updateAge).toBe(86400) // 1 day, matching better-auth's own default
     expect(result.sessionFields).toEqual(['userId', 'email', 'name'])
     expect(result.socialProviders).toEqual({})
     expect(result.betterAuthPlugins).toEqual([])
+    expect(result.betterAuthOptions).toEqual({})
+  })
+
+  it('should pass through betterAuthOptions unchanged', () => {
+    const result = normalizeAuthConfig({
+      betterAuthOptions: { baseURL: 'https://example.com' },
+    })
+
+    expect(result.betterAuthOptions).toEqual({ baseURL: 'https://example.com' })
   })
 
   it('should normalize email and password config', () => {
@@ -81,6 +91,14 @@ describe('normalizeAuthConfig', () => {
     expect(result.session.updateAge).toBe(false)
   })
 
+  it('should normalize a custom numeric session.updateAge', () => {
+    const result = normalizeAuthConfig({
+      session: { updateAge: 3600 },
+    })
+
+    expect(result.session.updateAge).toBe(3600)
+  })
+
   it('should normalize custom session fields', () => {
     const result = normalizeAuthConfig({
       sessionFields: ['userId', 'email', 'role'],
@@ -120,22 +138,24 @@ describe('normalizeAuthConfig', () => {
     expect(result.extendUserList.fields).toHaveProperty('role')
   })
 
-  it('should include custom sendEmail function', () => {
-    const mockSendEmail = async () => {}
+  it('should include custom sendResetPassword and sendVerificationEmail functions', () => {
+    const mockSendResetPassword = async () => {}
+    const mockSendVerificationEmail = async () => {}
 
     const result = normalizeAuthConfig({
-      sendEmail: mockSendEmail,
+      emailAndPassword: { enabled: true, sendResetPassword: mockSendResetPassword },
+      emailVerification: { enabled: true, sendVerificationEmail: mockSendVerificationEmail },
     })
 
-    expect(result.sendEmail).toBe(mockSendEmail)
+    expect(result.emailAndPassword.sendResetPassword).toBe(mockSendResetPassword)
+    expect(result.emailVerification.sendVerificationEmail).toBe(mockSendVerificationEmail)
   })
 
-  it('should provide default sendEmail that logs to console', () => {
+  it('should provide default sendResetPassword and sendVerificationEmail that log to console', () => {
     const result = normalizeAuthConfig({})
 
-    expect(typeof result.sendEmail).toBe('function')
-    // Default sendEmail should be a function that accepts email params
-    expect(result.sendEmail.length).toBe(1)
+    expect(typeof result.emailAndPassword.sendResetPassword).toBe('function')
+    expect(typeof result.emailVerification.sendVerificationEmail).toBe('function')
   })
 
   it('should include betterAuthPlugins', () => {
@@ -165,6 +185,44 @@ describe('normalizeAuthConfig', () => {
     expect(result.access.user).toBe(userAccess)
     expect(result.access.session).toBe(sessionAccess)
   })
+
+  describe('models.tableName (issue #862)', () => {
+    it('defaults tableName to undefined for unrenamed models', () => {
+      const result = normalizeAuthConfig({})
+
+      expect(result.models.user.tableName).toBeUndefined()
+      expect(result.models.session.tableName).toBeUndefined()
+      expect(result.models.account.tableName).toBeUndefined()
+      expect(result.models.verification.tableName).toBeUndefined()
+    })
+
+    it('defaults tableName to the renamed modelName, matching pre-#862 behaviour', () => {
+      const result = normalizeAuthConfig({
+        user: { modelName: 'AuthUser' },
+      })
+
+      expect(result.models.user.modelName).toBe('AuthUser')
+      expect(result.models.user.tableName).toBe('AuthUser')
+    })
+
+    it('resolves an explicit tableName independent of modelName', () => {
+      const result = normalizeAuthConfig({
+        user: { modelName: 'AuthUser', tableName: 'user' },
+      })
+
+      expect(result.models.user.modelName).toBe('AuthUser')
+      expect(result.models.user.tableName).toBe('user')
+    })
+
+    it('honours an explicit tableName even when modelName is left at its default', () => {
+      const result = normalizeAuthConfig({
+        session: { tableName: 'sessions' },
+      })
+
+      expect(result.models.session.modelName).toBe('Session')
+      expect(result.models.session.tableName).toBe('sessions')
+    })
+  })
 })
 
 describe('authPlugin', () => {

package/tests/derive-auth-lists.test.ts

@@ -44,6 +44,13 @@ describe('deriveAuthLists - default behaviour (no overrides)', () => {
     expect(lists.User.fields.accounts.ref).toBe('Account.user')
   })
 
+  it('marks Session/Verification expiresAt as DB-required, matching better-auth (issue #863)', () => {
+    const { lists } = deriveAuthLists(defaultModels)
+
+    expect(lists.Session.fields.expiresAt.db?.isNullable).toBe(false)
+    expect(lists.Verification.fields.expiresAt.db?.isNullable).toBe(false)
+  })
+
   it('emits no table @@map and no scalar @map for default keys', () => {
     const { lists } = deriveAuthLists(defaultModels)
 
@@ -108,6 +115,13 @@ describe('deriveAuthLists - user FK shape mirrors better-auth (issue #679)', ()
     }
   })
 
+  it('marks the user FK non-nullable, matching better-auth (issue #863)', () => {
+    const { lists } = deriveAuthLists(defaultModels)
+
+    expect(lists.Session.fields.user.db?.isNullable).toBe(false)
+    expect(lists.Account.fields.user.db?.isNullable).toBe(false)
+  })
+
   it('keeps the cascade extendPrismaSchema alongside a userId column override', () => {
     const models: NormalizedAuthModels = {
       user: { modelName: 'User', fields: {} },
@@ -126,11 +140,16 @@ describe('deriveAuthLists - user FK shape mirrors better-auth (issue #679)', ()
 })
 
 describe('deriveAuthLists - custom modelName overrides', () => {
+  // `deriveAuthLists` is the pure derivation step: it consumes an already-
+  // resolved `tableName` rather than re-deriving one from `modelName`. That
+  // default derivation (tableName follows modelName when it differs from the
+  // better-auth default) lives in `normalizeModelConfig` (config/index.ts) —
+  // mirror its output here since these fixtures bypass normalization.
   const customModels: NormalizedAuthModels = {
-    user: { modelName: 'AuthUser', fields: {} },
-    session: { modelName: 'AuthSession', fields: {} },
-    account: { modelName: 'AuthAccount', fields: {} },
-    verification: { modelName: 'AuthVerification', fields: {} },
+    user: { modelName: 'AuthUser', tableName: 'AuthUser', fields: {} },
+    session: { modelName: 'AuthSession', tableName: 'AuthSession', fields: {} },
+    account: { modelName: 'AuthAccount', tableName: 'AuthAccount', fields: {} },
+    verification: { modelName: 'AuthVerification', tableName: 'AuthVerification', fields: {} },
   }
 
   it('derives list keys from modelName', () => {
@@ -179,6 +198,61 @@ describe('deriveAuthLists - custom modelName overrides', () => {
   })
 })
 
+describe('deriveAuthLists - tableName independent of modelName (issue #862)', () => {
+  it('emits @@map from tableName even though modelName is unchanged', () => {
+    const models: NormalizedAuthModels = {
+      user: { modelName: 'User', tableName: 'users', fields: {} },
+      session: { modelName: 'Session', fields: {} },
+      account: { modelName: 'Account', fields: {} },
+      verification: { modelName: 'Verification', fields: {} },
+    }
+
+    const { keys, lists } = deriveAuthLists(models)
+
+    // The list key follows modelName, unaffected by tableName.
+    expect(keys.user).toBe('User')
+    expect(lists.User.db?.map).toBe('users')
+  })
+
+  it('adopts a better-auth default lowercase table under a prefixed list key', () => {
+    // The shape issue #862 exists for: a prefixed list key (to avoid
+    // colliding with the app's own domain User) whose live table is still
+    // better-auth's own default lowercase name.
+    const models: NormalizedAuthModels = {
+      user: { modelName: 'AuthUser', tableName: 'user', fields: {} },
+      session: { modelName: 'AuthSession', tableName: 'session', fields: {} },
+      account: { modelName: 'AuthAccount', tableName: 'account', fields: {} },
+      verification: { modelName: 'AuthVerification', tableName: 'verification', fields: {} },
+    }
+
+    const { keys, lists } = deriveAuthLists(models)
+
+    expect(keys).toEqual({
+      user: 'AuthUser',
+      session: 'AuthSession',
+      account: 'AuthAccount',
+      verification: 'AuthVerification',
+    })
+    expect(lists.AuthUser.db?.map).toBe('user')
+    expect(lists.AuthSession.db?.map).toBe('session')
+    expect(lists.AuthAccount.db?.map).toBe('account')
+    expect(lists.AuthVerification.db?.map).toBe('verification')
+  })
+
+  it('emits no @@map when tableName is unset, even with a renamed modelName', () => {
+    const models: NormalizedAuthModels = {
+      user: { modelName: 'AuthUser', fields: {} },
+      session: { modelName: 'Session', fields: {} },
+      account: { modelName: 'Account', fields: {} },
+      verification: { modelName: 'Verification', fields: {} },
+    }
+
+    const { lists } = deriveAuthLists(models)
+
+    expect(lists.AuthUser.db?.map).toBeUndefined()
+  })
+})
+
 describe('deriveAuthLists - custom field column maps', () => {
   const models: NormalizedAuthModels = {
     user: { modelName: 'AuthUser', fields: { name: 'full_name', emailVerified: 'is_verified' } },
@@ -229,7 +303,7 @@ describe('deriveAuthLists - schema placement', () => {
 
   it('carries both @@map and @@schema for renamed + relocated lists', () => {
     const models: NormalizedAuthModels = {
-      user: { modelName: 'AuthUser', fields: {}, schema: 'auth' },
+      user: { modelName: 'AuthUser', tableName: 'AuthUser', fields: {}, schema: 'auth' },
       session: { modelName: 'AuthSession', fields: {}, schema: 'auth' },
       account: { modelName: 'AuthAccount', fields: {}, schema: 'auth' },
       verification: { modelName: 'AuthVerification', fields: {}, schema: 'auth' },