@opensaas/stack-auth 0.38.0 → 0.39.0

package/src/config/types.ts

@@ -203,6 +203,14 @@ export type AuthAccessConfig = {
   account?: ListConfig<any>['access']
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   verification?: ListConfig<any>['access']
+  /**
+   * Access control for the `RateLimit` list — only meaningful when
+   * `rateLimit.storage: 'database'` derives it. Per ADR-0013 the list ships
+   * closed like the other four; grant access here (e.g. to inspect throttled
+   * keys in the Admin UI).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  rateLimit?: ListConfig<any>['access']
 }
 
 export type AuthModelConfig = {
@@ -413,6 +421,22 @@ export type AuthConfig = {
    * Rate limiting configuration
    * Controls rate limiting for authentication endpoints
    *
+   * `storage` mirrors better-auth's own `rateLimit.storage` option
+   * (`'memory' | 'database' | 'secondary-storage'`, default `'memory'`). Set
+   * it to `'database'` to persist the limiter across restarts/instances — the
+   * plugin then derives a fifth `RateLimit` Auth list (per ADR-0007) so the
+   * required table exists in the generated Prisma schema, following the same
+   * adoption knobs (`modelName`/`fields`/`tableName`/`schema`) the other four
+   * models carry. Derivation keys off `storage` alone — `enabled: false` with
+   * `storage: 'database'` still produces the list, since better-auth still
+   * expects the table regardless of whether the limiter is currently active
+   * (`enabled` is routinely environment-driven; tying the schema to it would
+   * make dev/prod schemas differ).
+   *
+   * Setting `storage` via `betterAuthOptions.rateLimit.storage` is rejected —
+   * use this option instead, since it also has schema consequences the
+   * passthrough can't apply.
+   *
    * @example
    * ```typescript
    * // Disable rate limiting for testing
@@ -426,6 +450,12 @@ export type AuthConfig = {
    *   window: 60,  // 60 seconds
    *   max: 100,    // 100 requests per window
    * }
+   *
+   * // Persist the limiter in the database (derives a RateLimit list)
+   * rateLimit: {
+   *   enabled: true,
+   *   storage: 'database',
+   * }
    * ```
    */
   rateLimit?: {
@@ -440,7 +470,12 @@ export type AuthConfig = {
      * @default 100
      */
     max?: number
-  }
+    /**
+     * Where better-auth persists the rate limiter.
+     * @default 'memory'
+     */
+    storage?: 'memory' | 'database' | 'secondary-storage'
+  } & AuthModelConfig
 
   /**
    * Escape hatch for better-auth options the stack doesn't model — typed as
@@ -498,7 +533,8 @@ export type NormalizedAuthModelConfig = {
 }
 
 /**
- * Resolved auth model configuration for all four better-auth models.
+ * Resolved auth model configuration for all four better-auth models, plus an
+ * optional fifth for the database-backed rate limiter.
  * Consumed by the Auth-list derivation and the runtime user-key resolution.
  */
 export type NormalizedAuthModels = {
@@ -506,6 +542,12 @@ export type NormalizedAuthModels = {
   session: NormalizedAuthModelConfig
   account: NormalizedAuthModelConfig
   verification: NormalizedAuthModelConfig
+  /**
+   * Present only when `rateLimit.storage === 'database'` — derives a fifth
+   * `RateLimit` Auth list. Absent (not `undefined`-valued) otherwise, so
+   * `Object.values(models)` never yields a model-less entry.
+   */
+  rateLimit?: NormalizedAuthModelConfig
 }
 
 /**
@@ -545,5 +587,6 @@ export type NormalizedAuthConfig = Required<
     enabled: boolean
     window?: number
     max?: number
+    storage?: 'memory' | 'database' | 'secondary-storage'
   }
 }

package/src/server/get-session-from-auth.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import type { OpenSaasConfig, AccessContext, Session } from '@opensaas/stack-core'
+import { emailOTP } from 'better-auth/plugins'
+import { createAuth, getSessionFromAuth } from './index.js'
+
+// Type-level regression coverage for #906: `getSessionFromAuth` must accept
+// an auth instance from either `createAuth()` overload — the widened
+// `Auth<BetterAuthOptions>` returned with no plugin tuple, and the narrowed
+// `Auth<ResolvedBetterAuthOptions<TPlugins>>` returned when one is passed —
+// with no cast and no intermediate widening assignment. `Parameters<typeof
+// createAuth>` on the overloaded export resolves against its last (generic)
+// signature rather than the call-site-selected one, so each call shape is
+// wrapped in its own ordinary function and read back via `typeof`, mirroring
+// `build-better-auth-options.test.ts`.
+type TestPlugins = [ReturnType<typeof emailOTP>]
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithNoPlugins(
+  config: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+) {
+  return createAuth(config, context)
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- referenced only via `typeof` below
+function callWithPlugins(
+  config: OpenSaasConfig | Promise<OpenSaasConfig>,
+  context: AccessContext | Promise<AccessContext>,
+  plugins: TestPlugins,
+) {
+  return createAuth(config, context, plugins)
+}
+
+type WidenedAuth = ReturnType<typeof callWithNoPlugins>
+type NarrowedAuth = ReturnType<typeof callWithPlugins>
+
+describe('getSessionFromAuth accepts either createAuth() overload (#906)', () => {
+  it('accepts the widened Auth<BetterAuthOptions> instance with no cast', () => {
+    expectTypeOf<WidenedAuth>().toExtend<Parameters<typeof getSessionFromAuth>[0]>()
+  })
+
+  it('accepts the narrowed, plugin-typed Auth instance with no cast', () => {
+    // This is the exact case #906 reported as a type error: a `createAuth`
+    // instance narrowed by a plugin tuple, passed straight into
+    // `getSessionFromAuth` without widening it back to `Auth<BetterAuthOptions>`.
+    expectTypeOf<NarrowedAuth>().toExtend<Parameters<typeof getSessionFromAuth>[0]>()
+  })
+
+  it('return type stays Promise<Session | null>, unchanged by the widened/narrowed instance', () => {
+    expectTypeOf(getSessionFromAuth).returns.toEqualTypeOf<Promise<Session | null>>()
+  })
+})

package/src/server/index.ts

@@ -111,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 (
@@ -330,12 +345,19 @@ export async function buildBetterAuthOptions<const TPlugins extends readonly Bet
         {} 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,
 
@@ -565,9 +587,19 @@ function resolveSessionField(
  * 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.
+ *
+ * `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,
 ): Promise<Session | null> {

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'
 
 /**
@@ -23,6 +23,14 @@ type BetterAuthFieldAttribute = {
   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
 }
 
 /**
@@ -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')
+  })
+})

package/tests/config.test.ts

@@ -223,6 +223,82 @@ describe('normalizeAuthConfig', () => {
       expect(result.models.session.tableName).toBe('sessions')
     })
   })
+
+  describe('models.rateLimit (issue #909)', () => {
+    it('is absent when rateLimit is not configured', () => {
+      const result = normalizeAuthConfig({})
+
+      expect(result.models.rateLimit).toBeUndefined()
+    })
+
+    it('is absent when storage is "memory" or unset', () => {
+      expect(normalizeAuthConfig({ rateLimit: { enabled: true } }).models.rateLimit).toBeUndefined()
+      expect(
+        normalizeAuthConfig({ rateLimit: { enabled: true, storage: 'memory' } }).models.rateLimit,
+      ).toBeUndefined()
+    })
+
+    it('is absent when storage is "secondary-storage"', () => {
+      expect(
+        normalizeAuthConfig({ rateLimit: { enabled: true, storage: 'secondary-storage' } }).models
+          .rateLimit,
+      ).toBeUndefined()
+    })
+
+    it('is present with the default RateLimit model name when storage is "database"', () => {
+      const result = normalizeAuthConfig({ rateLimit: { enabled: true, storage: 'database' } })
+
+      expect(result.models.rateLimit).toEqual({
+        modelName: 'RateLimit',
+        tableName: undefined,
+        fields: {},
+      })
+    })
+
+    it('is present even when enabled is false, since better-auth still expects the table', () => {
+      const result = normalizeAuthConfig({ rateLimit: { enabled: false, storage: 'database' } })
+
+      expect(result.models.rateLimit).toBeDefined()
+      expect(result.models.rateLimit?.modelName).toBe('RateLimit')
+    })
+
+    it('honours a custom modelName/tableName/fields/schema on the rateLimit model', () => {
+      const result = normalizeAuthConfig({
+        rateLimit: {
+          enabled: true,
+          storage: 'database',
+          modelName: 'AuthRateLimit',
+          tableName: 'rate_limit',
+          fields: { key: 'limit_key' },
+          schema: 'auth',
+        },
+      })
+
+      expect(result.models.rateLimit).toEqual({
+        modelName: 'AuthRateLimit',
+        tableName: 'rate_limit',
+        fields: { key: 'limit_key' },
+        schema: 'auth',
+      })
+    })
+
+    it('resolves the plugin-level schema default for the rateLimit model like the other four', () => {
+      const result = normalizeAuthConfig({
+        schema: 'auth',
+        rateLimit: { enabled: true, storage: 'database' },
+      })
+
+      expect(result.models.rateLimit?.schema).toBe('auth')
+      expect(result.models.user.schema).toBe('auth')
+    })
+
+    it('keeps storage on the normalized top-level rateLimit config', () => {
+      const result = normalizeAuthConfig({ rateLimit: { enabled: true, storage: 'database' } })
+
+      expect(result.rateLimit?.storage).toBe('database')
+      expect(result.rateLimit?.enabled).toBe(true)
+    })
+  })
 })
 
 describe('authPlugin', () => {
@@ -585,4 +661,89 @@ describe('authPlugin', () => {
       expect(result.lists.User.access).toBe(extendAccess)
     })
   })
+
+  describe('RateLimit list (issue #909)', () => {
+    it('does not inject a RateLimit list when rateLimit is unconfigured', async () => {
+      const result = await config({
+        plugins: [authPlugin({})],
+        lists: {},
+      })
+
+      expect(result.lists).not.toHaveProperty('RateLimit')
+    })
+
+    it('does not inject a RateLimit list for storage "memory" or "secondary-storage"', async () => {
+      const memory = await config({
+        plugins: [authPlugin({ rateLimit: { enabled: true, storage: 'memory' } })],
+        lists: {},
+      })
+      expect(memory.lists).not.toHaveProperty('RateLimit')
+
+      const secondary = await config({
+        plugins: [authPlugin({ rateLimit: { enabled: true, storage: 'secondary-storage' } })],
+        lists: {},
+      })
+      expect(secondary.lists).not.toHaveProperty('RateLimit')
+    })
+
+    it('injects a RateLimit list when storage is "database"', async () => {
+      const result = await config({
+        plugins: [authPlugin({ rateLimit: { enabled: true, storage: 'database' } })],
+        lists: {},
+      })
+
+      const rateLimit = result.lists.RateLimit
+      expect(rateLimit).toBeDefined()
+      expect(rateLimit.fields).toHaveProperty('key')
+      expect(rateLimit.fields).toHaveProperty('count')
+      expect(rateLimit.fields).toHaveProperty('lastRequest')
+    })
+
+    it('injects a RateLimit list even when enabled is false, since better-auth still expects the table', async () => {
+      const result = await config({
+        plugins: [authPlugin({ rateLimit: { enabled: false, storage: 'database' } })],
+        lists: {},
+      })
+
+      expect(result.lists.RateLimit).toBeDefined()
+    })
+
+    it('ships the RateLimit list closed by default (ADR-0013)', async () => {
+      const result = await config({
+        plugins: [authPlugin({ rateLimit: { enabled: true, storage: 'database' } })],
+        lists: {},
+      })
+
+      expect(result.lists.RateLimit.access).toBeUndefined()
+    })
+
+    it('applies access.rateLimit to the derived list', async () => {
+      const rateLimitQuery = () => true
+      const result = await config({
+        plugins: [
+          authPlugin({
+            rateLimit: { enabled: true, storage: 'database' },
+            access: { rateLimit: { operation: { query: rateLimitQuery } } },
+          }),
+        ],
+        lists: {},
+      })
+
+      expect(result.lists.RateLimit.access?.operation?.query).toBe(rateLimitQuery)
+    })
+
+    it('respects a custom modelName on the rateLimit config', async () => {
+      const result = await config({
+        plugins: [
+          authPlugin({
+            rateLimit: { enabled: true, storage: 'database', modelName: 'AuthRateLimit' },
+          }),
+        ],
+        lists: {},
+      })
+
+      expect(result.lists).toHaveProperty('AuthRateLimit')
+      expect(result.lists).not.toHaveProperty('RateLimit')
+    })
+  })
 })

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

@@ -344,6 +344,110 @@ describe('deriveAuthLists - schema placement', () => {
   })
 })
 
+describe('deriveAuthLists - RateLimit list (rateLimit.storage === "database")', () => {
+  it('is absent when no rateLimit model is supplied', () => {
+    const { keys, lists } = deriveAuthLists(defaultModels)
+
+    expect(keys.rateLimit).toBeUndefined()
+    expect(lists.RateLimit).toBeUndefined()
+    expect(Object.keys(lists).sort()).toEqual(['Account', 'Session', 'User', 'Verification'])
+  })
+
+  it('derives a RateLimit list keyed by the default model name when present', () => {
+    const models: NormalizedAuthModels = {
+      ...defaultModels,
+      rateLimit: { modelName: 'RateLimit', fields: {} },
+    }
+
+    const { keys, lists } = deriveAuthLists(models)
+
+    expect(keys.rateLimit).toBe('RateLimit')
+    expect(Object.keys(lists).sort()).toEqual([
+      'Account',
+      'RateLimit',
+      'Session',
+      'User',
+      'Verification',
+    ])
+  })
+
+  it('mirrors better-auth’s rateLimit table shape: key/count/lastRequest, all required, no defaults', () => {
+    const models: NormalizedAuthModels = {
+      ...defaultModels,
+      rateLimit: { modelName: 'RateLimit', fields: {} },
+    }
+
+    const { lists } = deriveAuthLists(models)
+    const rateLimit = lists.RateLimit
+
+    expect(rateLimit.fields.key.type).toBe('text')
+    expect(rateLimit.fields.key.isIndexed).toBe('unique')
+    expect(rateLimit.fields.key.validation?.isRequired).toBe(true)
+    expect(rateLimit.fields.key.defaultValue).toBeUndefined()
+
+    expect(rateLimit.fields.count.type).toBe('integer')
+    expect(rateLimit.fields.count.validation?.isRequired).toBe(true)
+    expect(rateLimit.fields.count.db?.isNullable).toBe(false)
+    expect(rateLimit.fields.count.defaultValue).toBeUndefined()
+
+    expect(rateLimit.fields.lastRequest.type).toBe('bigInt')
+    expect(rateLimit.fields.lastRequest.validation?.isRequired).toBe(true)
+    expect(rateLimit.fields.lastRequest.db?.isNullable).toBe(false)
+    expect(rateLimit.fields.lastRequest.defaultValue).toBeUndefined()
+
+    // Exactly these three fields — no createdAt/updatedAt columns on this list.
+    expect(Object.keys(rateLimit.fields).sort()).toEqual(['count', 'key', 'lastRequest'])
+  })
+
+  it('does not opt into auto-timestamps, unlike the other four Auth lists', () => {
+    const models: NormalizedAuthModels = {
+      ...defaultModels,
+      rateLimit: { modelName: 'RateLimit', fields: {} },
+    }
+
+    const { lists } = deriveAuthLists(models)
+
+    expect(lists.RateLimit.db?.timestamps).toBeUndefined()
+    expect(lists.User.db?.timestamps).toBe(true)
+  })
+
+  it('applies a custom modelName, tableName, field column maps, and schema like the other models', () => {
+    const models: NormalizedAuthModels = {
+      ...defaultModels,
+      rateLimit: {
+        modelName: 'AuthRateLimit',
+        tableName: 'rate_limit',
+        fields: { key: 'limit_key', count: 'hit_count', lastRequest: 'last_hit_at' },
+        schema: 'auth',
+      },
+    }
+
+    const { keys, lists } = deriveAuthLists(models)
+
+    expect(keys.rateLimit).toBe('AuthRateLimit')
+    const rateLimit = lists.AuthRateLimit
+    expect(rateLimit.db?.map).toBe('rate_limit')
+    expect(rateLimit.db?.schema).toBe('auth')
+    expect(rateLimit.fields.key.db?.map).toBe('limit_key')
+    expect(rateLimit.fields.count.db?.map).toBe('hit_count')
+    expect(rateLimit.fields.lastRequest.db?.map).toBe('last_hit_at')
+  })
+
+  it('ships closed (no access) unless accessConfig.rateLimit is supplied', () => {
+    const models: NormalizedAuthModels = {
+      ...defaultModels,
+      rateLimit: { modelName: 'RateLimit', fields: {} },
+    }
+
+    const { lists: closed } = deriveAuthLists(models)
+    expect(closed.RateLimit.access).toBeUndefined()
+
+    const rateLimitAccess = { operation: { query: () => true } }
+    const { lists: open } = deriveAuthLists(models, {}, { rateLimit: rateLimitAccess })
+    expect(open.RateLimit.access).toBe(rateLimitAccess)
+  })
+})
+
 describe('deriveAuthLists - extendUserList', () => {
   it('adds custom fields to the derived user list', () => {
     const { lists } = deriveAuthLists(