@opensaas/stack-auth 0.37.0 → 0.39.0

package/src/server/index.ts

@@ -1,11 +1,58 @@
 import { betterAuth } from 'better-auth'
 import { prismaAdapter } from 'better-auth/adapters/prisma'
 import { nextCookies } from 'better-auth/next-js'
-import type { BetterAuthOptions } from 'better-auth'
-import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core'
+import type { Auth, BetterAuthOptions, BetterAuthPlugin } from 'better-auth'
+import type { OpenSaasConfig, AccessContext, Session } from '@opensaas/stack-core'
 import type { DatabaseConfig } from '@opensaas/stack-core/internal'
 import type { NormalizedAuthConfig, NormalizedAuthModelConfig } from '../config/types.js'
 
+/**
+ * The `BetterAuthOptions` shape produced when an app's own plugin tuple is
+ * passed to `buildBetterAuthOptions()`/`createAuth()` — the tuple plus the
+ * `nextCookies()` plugin the stack always appends last. Carrying the literal
+ * tuple type (rather than the widened `BetterAuthPlugin[]`) is what lets
+ * `betterAuth()` re-infer plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape from the resulting options object.
+ */
+type ResolvedBetterAuthOptions<TPlugins extends readonly BetterAuthPlugin[]> = Omit<
+  BetterAuthOptions,
+  'plugins'
+> & {
+  plugins: [...TPlugins, ReturnType<typeof nextCookies>]
+}
+
+/**
+ * Guard against the supplied plugin tuple silently drifting from the plugin
+ * array actually resolved from `authPlugin({ betterAuthPlugins })` — the
+ * supplied tuple exists for typing only, so if it isn't the exact same
+ * instances in the exact same order, the type it produces would be a lie
+ * about what `betterAuth()` is actually constructed with.
+ */
+function assertPluginTupleMatchesResolved(
+  supplied: readonly BetterAuthPlugin[],
+  resolved: readonly BetterAuthPlugin[],
+): void {
+  if (supplied.length !== resolved.length) {
+    throw new Error(
+      '[@opensaas/stack-auth] The plugin tuple passed to `buildBetterAuthOptions()` / `createAuth()` ' +
+        `has ${supplied.length} plugin(s), but the plugin array resolved from \`authPlugin({ ` +
+        `betterAuthPlugins })\` has ${resolved.length}. Pass the exact same array (without ` +
+        '`nextCookies()` — the stack appends that itself).',
+    )
+  }
+
+  const mismatchIndex = supplied.findIndex((plugin, index) => plugin !== resolved[index])
+  if (mismatchIndex !== -1) {
+    throw new Error(
+      '[@opensaas/stack-auth] The plugin tuple passed to `buildBetterAuthOptions()` / `createAuth()` ' +
+        `does not match the plugin array resolved from \`authPlugin({ betterAuthPlugins })\` at index ` +
+        `${mismatchIndex} (got plugin "${supplied[mismatchIndex]?.id}", expected the same instance as ` +
+        `"${resolved[mismatchIndex]?.id}"). Pass the exact same array — same instances, same order.`,
+    )
+  }
+}
+
 /**
  * Get better-auth database configuration from OpenSaas config
  */
@@ -64,6 +111,21 @@ function assertNoUnsupportedPassthroughKeys(betterAuthOptions: Record<string, un
     )
   }
 
+  const rateLimitOptions = betterAuthOptions.rateLimit
+  if (
+    rateLimitOptions &&
+    typeof rateLimitOptions === 'object' &&
+    !Array.isArray(rateLimitOptions) &&
+    'storage' in rateLimitOptions
+  ) {
+    throw new Error(
+      '[@opensaas/stack-auth] `betterAuthOptions.rateLimit.storage` is not supported — it has ' +
+        'schema consequences (deriving the `RateLimit` list) that a passthrough cannot also ' +
+        "apply to the generated Prisma schema. Use `authPlugin({ rateLimit: { storage: 'database' } })` " +
+        'instead.',
+    )
+  }
+
   for (const model of MODELS_WITH_NO_ADDITIONAL_FIELDS_PASSTHROUGH) {
     const modelOptions = betterAuthOptions[model]
     if (
@@ -125,21 +187,55 @@ function mergeBetterAuthOptions(
  * authoritative for everything it models; the app's additions on top become
  * an explicit, reviewable diff instead of a parallel, hand-duplicated config.
  *
- * @example
+ * Called with just `(config, context)`, the return type is the widened
+ * `BetterAuthOptions` — `betterAuth()` infers its plugin/session types from
+ * the *literal* type of the options object, so constructing from this
+ * widened return erases plugin endpoints (e.g. `emailOTP()`'s
+ * `api.signInEmailOTP`) and a `customSession()` plugin's replaced session
+ * shape. **If your app reads `auth.api.*` in typed code and uses either of
+ * those, pass its plugin tuple as the third argument** — the exact same
+ * array already passed to `authPlugin({ betterAuthPlugins })` — so the
+ * return type carries the literal tuple instead:
+ *
  * ```typescript
  * import { betterAuth } from 'better-auth'
+ * import { emailOTP } from 'better-auth/plugins'
  * import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
  *
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
  * export const auth = betterAuth({
- *   ...(await buildBetterAuthOptions(config, context)),
+ *   ...(await buildBetterAuthOptions(config, context, appBetterAuthPlugins)),
  *   databaseHooks: { user: { create: { after: syncDomainUser } } },
  * })
+ * // auth.api.signInEmailOTP / auth.api.getSession()'s customSession shape are now typed.
  * ```
+ *
+ * The supplied tuple is for typing only — the array actually used at runtime
+ * is always the one resolved from `authPlugin({ betterAuthPlugins })`, with
+ * exactly one `nextCookies()` appended last. Passing a tuple that isn't the
+ * same plugin instances in the same order throws, so the two can't silently
+ * drift apart.
+ *
+ * Note `createAuth()`'s lazy Proxy does not behave identically to a real
+ * `Auth` instance for every property (see its own doc comment) — reach for
+ * this builder plus `betterAuth()` instead when the app reads `auth.api.*`
+ * in typed code.
  */
 export async function buildBetterAuthOptions(
   opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
   context: AccessContext | Promise<AccessContext>,
-): Promise<BetterAuthOptions> {
+): Promise<BetterAuthOptions>
+export async function buildBetterAuthOptions<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins: TPlugins,
+): Promise<ResolvedBetterAuthOptions<TPlugins>>
+export async function buildBetterAuthOptions<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins?: TPlugins,
+): Promise<BetterAuthOptions | ResolvedBetterAuthOptions<TPlugins>> {
   const resolvedConfig = await Promise.resolve(opensaasConfig)
   const resolvedContext = await Promise.resolve(context)
 
@@ -179,6 +275,11 @@ export async function buildBetterAuthOptions(
 
   assertNoUnsupportedPassthroughKeys(authConfig.betterAuthOptions as Record<string, unknown>)
 
+  const resolvedPlugins = authConfig.betterAuthPlugins || []
+  if (plugins) {
+    assertPluginTupleMatchesResolved(plugins, resolvedPlugins)
+  }
+
   // Build better-auth configuration
   const betterAuthConfig: BetterAuthOptions = {
     database: getDatabaseConfig(resolvedConfig.db, resolvedContext),
@@ -244,12 +345,19 @@ export async function buildBetterAuthOptions(
         {} as Record<string, { clientId: string; clientSecret: string }>,
       ),
 
-    // Rate limiting configuration
+    // Rate limiting configuration. `modelName`/`fields` are only forwarded
+    // when `models.rateLimit` was derived (rateLimit.storage === 'database')
+    // — mirroring the running instance's model options back to the table the
+    // `RateLimit` Auth list was derived from.
     rateLimit: authConfig.rateLimit
       ? {
           enabled: authConfig.rateLimit.enabled,
           window: authConfig.rateLimit.window,
           max: authConfig.rateLimit.max,
+          ...(authConfig.rateLimit.storage ? { storage: authConfig.rateLimit.storage } : {}),
+          ...(authConfig.models.rateLimit
+            ? toBetterAuthModelOptions(authConfig.models.rateLimit)
+            : {}),
         }
       : undefined,
 
@@ -259,47 +367,81 @@ export async function buildBetterAuthOptions(
     // 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()],
+    plugins: [...resolvedPlugins, nextCookies()],
   }
 
   return mergeBetterAuthOptions(
     betterAuthConfig as unknown as Record<string, unknown>,
     authConfig.betterAuthOptions as Record<string, unknown>,
-  ) as BetterAuthOptions
+  ) as BetterAuthOptions | ResolvedBetterAuthOptions<TPlugins>
 }
 
 /**
  * Create a better-auth instance from OpenSaas config
  * This should be called once at app startup
  *
- * @example
+ * Returns a lazy `Proxy` (see the caveat below), typed as `Auth<BetterAuthOptions>`
+ * when called with just `(config, context)` — the widened type, same erasure
+ * caveat as {@link buildBetterAuthOptions}'s no-argument form. **If your app
+ * reads `auth.api.*` in typed code and relies on a plugin's endpoints (e.g.
+ * `emailOTP()`) or a `customSession()`'s replaced session shape, pass its
+ * plugin tuple as the third argument** — the exact same array already passed
+ * to `authPlugin({ betterAuthPlugins })` — so the declared type carries the
+ * literal tuple instead:
+ *
  * ```typescript
  * // lib/auth.ts
  * import { createAuth } from '@opensaas/stack-auth/server'
  * import config from '../opensaas.config'
  * import { rawOpensaasContext } from '@/.opensaas/context'
  *
- * export const auth = createAuth(config, rawOpensaasContext)
+ * export const appBetterAuthPlugins = [emailOTP()] // same array passed to authPlugin({ betterAuthPlugins })
+ *
+ * export const auth = createAuth(config, rawOpensaasContext, appBetterAuthPlugins)
  * ```
+ *
+ * As with the builder, the supplied tuple is for typing only, and a tuple
+ * that isn't the same plugin instances in the same order throws.
+ *
+ * **Proxy caveat:** the lazy `Proxy` this returns does not behave identically
+ * to a real `Auth` instance for every property — every access, including a
+ * non-function property, is surfaced through an `async` wrapper (so e.g.
+ * `auth.options` reads back as a `Promise`, not the plain object a real
+ * instance would return synchronously). The declared type does not model
+ * this difference; where it matters, reach for {@link buildBetterAuthOptions}
+ * plus `betterAuth()` instead, which constructs a real instance.
  */
 export function createAuth(
   opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
   context: AccessContext | Promise<AccessContext>,
-) {
+): Auth<BetterAuthOptions>
+export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins: TPlugins,
+): Auth<ResolvedBetterAuthOptions<TPlugins>>
+export function createAuth<const TPlugins extends readonly BetterAuthPlugin[]>(
+  opensaasConfig: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins?: TPlugins,
+): Auth<BetterAuthOptions> | Auth<ResolvedBetterAuthOptions<TPlugins>> {
   // Resolve config and context asynchronously
   const configPromise = Promise.resolve(opensaasConfig)
   const contextPromise = Promise.resolve(context)
 
   // Create auth instance lazily when needed
-  let authInstance: ReturnType<typeof betterAuth> | null = null
-  let authPromise: Promise<ReturnType<typeof betterAuth>> | null = null
+  type AuthInstance = Auth<BetterAuthOptions> | Auth<ResolvedBetterAuthOptions<TPlugins>>
+  let authInstance: AuthInstance | null = null
+  let authPromise: Promise<AuthInstance> | null = null
 
   async function getAuthInstance() {
     if (authInstance) return authInstance
 
     if (!authPromise) {
       authPromise = (async () => {
-        const betterAuthConfig = await buildBetterAuthOptions(configPromise, contextPromise)
+        const betterAuthConfig = plugins
+          ? await buildBetterAuthOptions(configPromise, contextPromise, plugins)
+          : await buildBetterAuthOptions(configPromise, contextPromise)
         authInstance = betterAuth(betterAuthConfig)
         return authInstance
       })()
@@ -309,7 +451,7 @@ export function createAuth(
   }
 
   // Return a proxy that lazily initializes the auth instance
-  return new Proxy({} as ReturnType<typeof betterAuth>, {
+  return new Proxy({} as AuthInstance, {
     get(_, prop) {
       if (prop === 'then') {
         // Support await on the proxy itself
@@ -355,41 +497,131 @@ export function createAuth(
 }
 
 /**
- * Get session from better-auth and transform it to OpenSaas session format.
+ * Field names already warned about failing to resolve against a session, so a
+ * given field warns at most once per process rather than once per request.
+ */
+const unresolvedSessionFieldWarnings = new Set<string>()
+
+/**
+ * Warn (once per field, per process) that a `sessionFields` entry could not
+ * be resolved from the session shape `auth.api.getSession()` actually
+ * returned — naming the field and what keys were available to check, so the
+ * gap is visible here instead of surfacing later as an access-control
+ * function silently reading `undefined`.
+ */
+function warnUnresolvedSessionField(field: string, resolvedSession: Record<string, unknown>): void {
+  if (unresolvedSessionFieldWarnings.has(field)) return
+  unresolvedSessionFieldWarnings.add(field)
+
+  const user = isPlainObject(resolvedSession.user) ? resolvedSession.user : undefined
+  const sessionRow = isPlainObject(resolvedSession.session) ? resolvedSession.session : undefined
+
+  console.warn(
+    `[@opensaas/stack-auth] sessionFields: "${field}" was not found on the resolved session. ` +
+      `Checked its top-level keys (${Object.keys(resolvedSession).join(', ') || 'none'}), ` +
+      `its "user" object (${user ? Object.keys(user).join(', ') || 'none' : 'not present'}), ` +
+      `and its "session" object (${sessionRow ? Object.keys(sessionRow).join(', ') || 'none' : 'not present'}). ` +
+      `The field is omitted from the projected session. A \`customSession\` plugin that nests this ` +
+      `value elsewhere is the app's own to reconcile — see the \`sessionFields\` reference. ` +
+      `This warning will not repeat for "${field}".`,
+  )
+}
+
+/**
+ * Resolve a single `sessionFields` entry off the resolved better-auth
+ * session (whatever `auth.api.getSession()` returned — the default `{
+ * session, user }` shape, or a `customSession` plugin's replaced shape).
+ *
+ * `userId` is special-cased to the authenticated user's `id` — the
+ * documented default apps depend on. Every other name resolves against a
+ * fixed precedence so a collision between sources is predictable rather
+ * than incidental: a top-level key on the resolved session object, then the
+ * `user` object, then the `session` sub-object.
+ */
+function resolveSessionField(
+  field: string,
+  resolvedSession: Record<string, unknown>,
+): { found: true; value: unknown } | { found: false } {
+  const user = isPlainObject(resolvedSession.user) ? resolvedSession.user : undefined
+
+  if (field === 'userId') {
+    return user && 'id' in user ? { found: true, value: user.id } : { found: false }
+  }
+
+  if (field in resolvedSession) {
+    return { found: true, value: resolvedSession[field] }
+  }
+  if (user && field in user) {
+    return { found: true, value: user[field] }
+  }
+  const sessionRow = isPlainObject(resolvedSession.session) ? resolvedSession.session : undefined
+  if (sessionRow && field in sessionRow) {
+    return { found: true, value: sessionRow[field] }
+  }
+  return { found: false }
+}
+
+/**
+ * Get session from better-auth and transform it to OpenSaas session format —
+ * a flattened projection of `sessionFields` off the *resolved* session
+ * object, not just its `user` sub-object. This is what makes a
+ * `customSession` plugin's fields (added at the top level, or a
+ * session-only field like the admin plugin's `impersonatedBy`) reachable.
+ * See the `sessionFields` reference for the resolution precedence.
+ *
+ * Returns `null` only when there is genuinely no session — a resolved
+ * session with no `user` key (a `customSession` plugin that dropped it) is
+ * still a session and still gets projected, never misreported as anonymous.
+ * A listed field that can't be resolved from the session shape is omitted
+ * and warns once per field per process (see `warnUnresolvedSessionField`)
+ * instead of silently vanishing into an access-control function reading
+ * `undefined`.
+ *
+ * Errors from the underlying `auth.api.getSession()` call propagate rather
+ * than becoming `null` — collapsing a lookup failure (e.g. a session-store
+ * outage) into "anonymous" is indistinguishable from a mass sign-out under
+ * fail-closed access control, so the caller must see it.
+ *
+ * Not called by any generated code before this helper existed — apps used to
+ * hand-roll this same transform against `auth.api.getSession({ headers:
+ * await headers() })`. Exported as the single reusable implementation; 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.
  *
- * 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.
+ * `auth` is typed structurally over just the one member this function reads
+ * — `api.getSession` — rather than a single concrete `Auth<Options>`
+ * instantiation, so it accepts an instance from either `createAuth()`
+ * overload: the widened `Auth<BetterAuthOptions>`, or the narrowed
+ * `Auth<ResolvedBetterAuthOptions<TPlugins>>` returned when a plugin tuple is
+ * passed. `TResolvedSession` is inferred from whatever `auth.api.getSession`
+ * actually returns (the default `{ session, user }` shape, or a
+ * `customSession` plugin's replaced shape) — it is not constrained, so no
+ * `any`/`unknown` is introduced at the call boundary.
  */
-export async function getSessionFromAuth(
-  auth: ReturnType<typeof betterAuth>,
+export async function getSessionFromAuth<TResolvedSession>(
+  auth: { api: { getSession: (args: { headers: Headers }) => Promise<TResolvedSession> } },
   sessionFields: string[],
   headers: Headers,
-) {
-  try {
-    const session = await auth.api.getSession({ headers })
+): Promise<Session | null> {
+  const resolvedSession = await auth.api.getSession({ headers })
 
-    if (!session?.user) {
-      return null
-    }
+  if (!resolvedSession) {
+    return null
+  }
 
-    // Build session object with requested fields
-    const result: Record<string, unknown> = {}
+  const resolvedSessionRecord = resolvedSession as Record<string, unknown>
+  const result: Record<string, unknown> = {}
 
-    for (const field of sessionFields) {
-      if (field === 'userId') {
-        result.userId = session.user.id
-      } else if (field in session.user) {
-        result[field] = session.user[field as keyof typeof session.user]
-      }
+  for (const field of sessionFields) {
+    const resolved = resolveSessionField(field, resolvedSessionRecord)
+    if (resolved.found) {
+      result[field] = resolved.value
+    } else {
+      warnUnresolvedSessionField(field, resolvedSessionRecord)
     }
-
-    return result
-  } catch {
-    return null
   }
+
+  return result
 }
 
 export type { BetterAuthOptions }

package/src/server/schema-converter.ts

@@ -4,7 +4,7 @@
  */
 
 import { list } from '@opensaas/stack-core'
-import { text, timestamp, checkbox, integer } from '@opensaas/stack-core/fields'
+import { text, timestamp, checkbox, integer, bigInt } from '@opensaas/stack-core/fields'
 import type { ListConfig, FieldConfig } from '@opensaas/stack-core'
 
 /**
@@ -12,24 +12,32 @@ import type { ListConfig, FieldConfig } from '@opensaas/stack-core'
  * Inferred from better-auth internal types
  */
 type BetterAuthFieldAttribute = {
-  type: string // 'string' | 'number' | 'boolean' | 'date' | etc.
+  type: string | string[] // 'string' | 'number' | 'boolean' | 'date' | etc., or an enum array
   required?: boolean
   unique?: boolean
   references?: {
     model: string
     field: string
-    onDelete?: 'cascade' | 'set null' | 'restrict'
+    onDelete?: 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default'
   }
   defaultValue?: unknown
   returned?: boolean
   input?: boolean
+  /**
+   * "If the field should be a bigint on the database instead of integer" —
+   * only meaningful alongside `type: 'number'`. Modelled here so the `number`
+   * branch below can read it; better-auth's rate limiter is the only shipped
+   * example (`lastRequest`, a millisecond epoch that overflows a 32-bit
+   * `Int`), but any plugin can declare it (issue #917).
+   */
+  bigint?: boolean
 }
 
 /**
  * Better Auth table schema structure
  */
 type BetterAuthTableSchema = {
-  modelName: string
+  modelName?: string
   fields: Record<string, BetterAuthFieldAttribute>
 }
 
@@ -40,7 +48,7 @@ function convertField(
   fieldName: string,
   betterAuthField: BetterAuthFieldAttribute,
 ): FieldConfig | null {
-  const { type, required, unique, defaultValue, references } = betterAuthField
+  const { type, required, unique, defaultValue, references, bigint } = betterAuthField
 
   // System fields are auto-generated by OpenSaaS
   if (fieldName === 'id' || fieldName === 'createdAt' || fieldName === 'updatedAt') {
@@ -64,6 +72,16 @@ function convertField(
       })
 
     case 'number':
+      // A millisecond epoch (e.g. Date.now()) overflows a 32-bit Int, so a
+      // field declaring `bigint: true` must generate a BigInt column instead
+      // (issue #917) — matching what deriveAuthLists produces for the same
+      // upstream declaration (e.g. the rate limiter's `lastRequest`).
+      if (bigint) {
+        return bigInt({
+          validation: { isRequired: required },
+          defaultValue: typeof defaultValue === 'number' ? defaultValue : undefined,
+        })
+      }
       return integer({
         validation: { isRequired: required },
         defaultValue: typeof defaultValue === 'number' ? defaultValue : undefined,
@@ -137,10 +155,11 @@ export function convertTableToList(
 }
 
 /**
- * Base better-auth model keys — the four tables the auth plugin's own model
- * config (`user`/`session`/`account`/`verification`) can remap via `modelName`.
+ * Base better-auth model keys — the tables the auth plugin's own model config
+ * (`user`/`session`/`account`/`verification`, plus `rateLimit` when
+ * `rateLimit.storage: 'database'` derives it) can remap via `modelName`.
  */
-type BaseAuthModelKey = 'user' | 'session' | 'account' | 'verification'
+type BaseAuthModelKey = 'user' | 'session' | 'account' | 'verification' | 'rateLimit'
 
 /**
  * Resolved list key for each base better-auth model, as derived by
@@ -171,6 +190,8 @@ function resolveBaseModelKey(
       return baseModelKeys.account
     case 'verification':
       return baseModelKeys.verification
+    case 'ratelimit':
+      return baseModelKeys.rateLimit
     default:
       return undefined
   }

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

@@ -280,3 +280,76 @@ describe('adoptBetterAuthTables - clean-diff adoption (Auth lists ≠ app User)'
     expect(result.lists.AuthSession.fields.user.db?.foreignKey).toEqual({ map: 'user_id' })
   })
 })
+
+describe('adoptBetterAuthTables - rateLimit adoption (issue #909)', () => {
+  it('omits rateLimit from the fragment by default', () => {
+    const fragment = adoptBetterAuthTables()
+
+    expect(fragment.rateLimit).toBeUndefined()
+  })
+
+  it('adds a prefixed, database-storage rateLimit fragment when opted in', () => {
+    const fragment = adoptBetterAuthTables({ rateLimit: true })
+
+    expect(fragment.rateLimit).toEqual({
+      enabled: true,
+      storage: 'database',
+      modelName: 'AuthRateLimit',
+    })
+  })
+
+  it('honours a custom schema/prefix on the rateLimit fragment like the other four models', () => {
+    const fragment = adoptBetterAuthTables({
+      rateLimit: true,
+      schema: 'identity',
+      modelNamePrefix: 'BA',
+    })
+
+    expect(fragment.rateLimit).toEqual({
+      enabled: true,
+      storage: 'database',
+      modelName: 'BARateLimit',
+    })
+  })
+
+  it('useBetterAuthTableNames sets the rateLimit tableName to the better-auth default', () => {
+    const fragment = adoptBetterAuthTables({ rateLimit: true, useBetterAuthTableNames: true })
+
+    expect(fragment.rateLimit).toEqual({
+      enabled: true,
+      storage: 'database',
+      modelName: 'AuthRateLimit',
+      tableName: 'rateLimit',
+    })
+  })
+
+  it('merges a rateLimit field column map when provided', () => {
+    const fragment = adoptBetterAuthTables({
+      rateLimit: true,
+      fields: { rateLimit: { key: 'limit_key' } },
+    })
+
+    expect(fragment.rateLimit).toEqual({
+      enabled: true,
+      storage: 'database',
+      modelName: 'AuthRateLimit',
+      fields: { key: 'limit_key' },
+    })
+  })
+
+  it('composes with authPlugin to actually derive the fifth Auth list', async () => {
+    const result = await generationConfig({
+      db: { provider: 'postgresql' },
+      plugins: [
+        authPlugin({
+          ...adoptBetterAuthTables({ rateLimit: true }),
+          emailAndPassword: { enabled: true },
+        }),
+      ],
+      lists: {},
+    })
+
+    expect(result.lists).toHaveProperty('AuthRateLimit')
+    expect(result.lists.AuthRateLimit.db?.schema).toBe('auth')
+  })
+})