@opensaas/stack-auth 0.37.0 → 0.39.0

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(

package/tests/generated-fk-shape.test.ts

@@ -144,3 +144,84 @@ describe('generated auth schema — tableName independent of modelName (issue #8
     }
   })
 })
+
+describe('generated RateLimit schema mirrors better-auth exactly (issue #909)', () => {
+  it('does not add a RateLimit model when storage is unset', async () => {
+    const schema = await generateSchema({
+      db: { provider: 'sqlite' },
+      plugins: [authPlugin({ emailAndPassword: { enabled: true } })],
+      lists: {},
+    })
+
+    expect(schema).not.toContain('model RateLimit')
+  })
+
+  it('emits key (unique, non-null), count (non-null Int), lastRequest (non-null BigInt), no createdAt/updatedAt, no @default', async () => {
+    const schema = await generateSchema({
+      db: { provider: 'sqlite' },
+      plugins: [
+        authPlugin({
+          emailAndPassword: { enabled: true },
+          rateLimit: { enabled: true, storage: 'database' },
+        }),
+      ],
+      lists: {},
+    })
+
+    const block = modelBlock(schema, 'RateLimit')
+
+    expect(block).toMatch(/key\s+String\s+@unique/)
+    expect(block).toMatch(/count\s+Int\s/)
+    expect(block).not.toMatch(/count\s+Int\?/)
+    expect(block).toMatch(/lastRequest\s+BigInt\s/)
+    expect(block).not.toMatch(/lastRequest\s+BigInt\?/)
+
+    expect(block).not.toContain('createdAt')
+    expect(block).not.toContain('updatedAt')
+    // The system `id` field carries its own @default(cuid()) — only the
+    // three better-auth-mirrored columns must carry none.
+    expect(block).not.toMatch(/key\s+String\s+@unique\s+@default/)
+    expect(block).not.toMatch(/count\s+Int\s+@default/)
+    expect(block).not.toMatch(/lastRequest\s+BigInt\s+@default/)
+  })
+
+  it('honours a custom modelName/tableName/fields/schema on the rateLimit model', async () => {
+    const schema = await generateSchema({
+      db: { provider: 'postgresql' },
+      plugins: [
+        authPlugin({
+          emailAndPassword: { enabled: true },
+          rateLimit: {
+            enabled: true,
+            storage: 'database',
+            modelName: 'AuthRateLimit',
+            tableName: 'rate_limit',
+            fields: { key: 'limit_key', count: 'hit_count', lastRequest: 'last_hit_at' },
+          },
+        }),
+      ],
+      lists: {},
+    })
+
+    const block = modelBlock(schema, 'AuthRateLimit')
+    expect(block).toContain('@@map("rate_limit")')
+    expect(block).toContain('@map("limit_key")')
+    expect(block).toContain('@map("hit_count")')
+    expect(block).toContain('@map("last_hit_at")')
+  })
+
+  it('produces a RateLimit model even when enabled is false, since better-auth still expects the table', async () => {
+    const schema = await generateSchema({
+      db: { provider: 'sqlite' },
+      plugins: [
+        authPlugin({
+          emailAndPassword: { enabled: true },
+          rateLimit: { enabled: false, storage: 'database' },
+        }),
+      ],
+      lists: {},
+    })
+
+    expect(schema).toContain('model RateLimit')
+  })
+})

package/tests/plugin-schema-placement.test.ts

@@ -119,3 +119,42 @@ describe('authPlugin - schema placement (adopt existing auth-schema install)', (
     expect(result.db.schemas).toContain('auth_internal')
   })
 })
+
+describe('authPlugin - RateLimit list schema placement', () => {
+  it('places the RateLimit list in the configured schema and wires the datasource', async () => {
+    const result = await generationConfig({
+      db: { provider: 'postgresql' },
+      plugins: [
+        authPlugin({
+          schema: 'auth',
+          rateLimit: { enabled: true, storage: 'database', modelName: 'AuthRateLimit' },
+        }),
+      ],
+      lists: {},
+    })
+
+    expect(result.lists.AuthRateLimit.db).toEqual({ map: 'AuthRateLimit', schema: 'auth' })
+    expect(result.db.schemas).toContain('auth')
+  })
+
+  it('honours a per-model schema override independent of the plugin-level schema', async () => {
+    const result = await generationConfig({
+      db: { provider: 'postgresql' },
+      plugins: [
+        authPlugin({
+          schema: 'auth',
+          rateLimit: {
+            enabled: true,
+            storage: 'database',
+            modelName: 'AuthRateLimit',
+            schema: 'auth_internal',
+          },
+        }),
+      ],
+      lists: {},
+    })
+
+    expect(result.lists.AuthRateLimit.db?.schema).toBe('auth_internal')
+    expect(result.db.schemas).toContain('auth_internal')
+  })
+})

package/tests/rate-limit-e2e.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect, afterAll } from 'vitest'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { existsSync } from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createAuth } from '../src/server/index.js'
+import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core'
+
+/**
+ * Live end-to-end proof that the database-backed rate limiter (issue #909)
+ * actually works: it generates a real Prisma schema (with the derived
+ * `RateLimit` list), pushes it to a real SQLite database, constructs real
+ * `betterAuth()` instances against that database via `createAuth()` (the
+ * package's own source, not a stale build), and drives them through real
+ * HTTP-shaped requests via `auth.handler()`.
+ *
+ * This is the one guard in the suite that touches a live database, so it
+ * follows the same pattern as
+ * `packages/create-opensaas-app/tests/scaffold-first-run-guard.test.ts`
+ * (see ADR-0002): opt-in via an env flag, kept out of the fast unit lane, run
+ * only in the `e2e` CI job where `pnpm install && pnpm build` have already
+ * run. It borrows the `opensaas`/`prisma` binaries and the
+ * `@prisma/adapter-better-sqlite3` dependency from `examples/starter-auth`'s
+ * already-installed `node_modules` (symlinked into an OS temp dir) instead of
+ * adding a live-database toolchain to this package's own dependencies.
+ */
+
+const run = promisify(execFile)
+const here = path.dirname(new URL(import.meta.url).pathname)
+const repoRoot = path.resolve(here, '../../..')
+
+/** The `opensaas` CLI the temp project's `generate` step invokes. */
+const opensaasCli = path.join(repoRoot, 'packages/cli/dist/index.js')
+/** `createAuth()` (imported from source above) resolves `@opensaas/stack-core` through this build. */
+const coreDist = path.join(repoRoot, 'packages/core/dist')
+
+/** The toolchain (opensaas/prisma binaries + the sqlite adapter) borrowed from a working example. */
+const toolchainNodeModules = path.join(repoRoot, 'examples/starter-auth/node_modules')
+
+const guardEnabled = process.env.RUN_RATE_LIMIT_E2E === '1'
+
+const prerequisitesPresent =
+  guardEnabled &&
+  existsSync(opensaasCli) &&
+  existsSync(coreDist) &&
+  existsSync(path.join(toolchainNodeModules, '.bin', 'opensaas')) &&
+  existsSync(path.join(toolchainNodeModules, '.bin', 'prisma')) &&
+  existsSync(path.join(toolchainNodeModules, '@prisma', 'adapter-better-sqlite3'))
+
+/** Build the temp project's `opensaas.config.ts`: sqlite + a database-backed rate limiter. */
+function makeConfigSource(window: number, max: number): string {
+  return `import { config } from '@opensaas/stack-core'
+import { authPlugin } from '@opensaas/stack-auth'
+import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
+
+export default config({
+  plugins: [
+    authPlugin({
+      emailAndPassword: { enabled: true },
+      rateLimit: { enabled: true, window: ${window}, max: ${max}, storage: 'database' },
+    }),
+  ],
+  db: {
+    provider: 'sqlite',
+    prismaClientConstructor: (PrismaClient) => {
+      const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL || './dev.db' })
+      return new PrismaClient({ adapter })
+    },
+  },
+  lists: {},
+})
+`
+}
+
+/** A GET request against a real (rate-limited) better-auth endpoint from a fixed "client". */
+function sessionRequest(ip: string): Request {
+  return new Request('http://localhost:3000/api/auth/get-session', {
+    method: 'GET',
+    headers: { 'x-forwarded-for': ip },
+  })
+}
+
+/** Scaffold a fresh temp project with the given window/max and push its schema. Returns the project dir. */
+async function setupProject(window: number, max: number): Promise<string> {
+  const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'opensaas-ratelimit-e2e-'))
+  const dir = path.join(tmpRoot, 'project')
+  await fsp.mkdir(dir, { recursive: true })
+
+  await fsp.writeFile(path.join(dir, 'opensaas.config.ts'), makeConfigSource(window, max))
+  await fsp.writeFile(
+    path.join(dir, 'package.json'),
+    JSON.stringify(
+      { name: 'ratelimit-e2e-project', version: '0.0.0', private: true, type: 'module' },
+      null,
+      2,
+    ),
+  )
+  await fsp.writeFile(path.join(dir, '.env'), 'DATABASE_URL=file:./dev.db\n')
+  await fsp.symlink(toolchainNodeModules, path.join(dir, 'node_modules'))
+
+  const env = {
+    ...process.env,
+    DATABASE_URL: 'file:./dev.db',
+    BETTER_AUTH_SECRET: 'e2e-test-secret-not-for-production-0000000000',
+    BETTER_AUTH_URL: 'http://localhost:3000',
+  }
+  const binDir = path.join(dir, 'node_modules', '.bin')
+  await run(path.join(binDir, 'opensaas'), ['generate'], { cwd: dir, env })
+  await run(path.join(binDir, 'prisma'), ['db', 'push'], { cwd: dir, env })
+
+  return dir
+}
+
+/**
+ * Import the temp project's config + generated context and build a real auth
+ * instance via `createAuth()`. Each call produces a genuinely separate
+ * `betterAuth()` instance — `createAuth()`'s lazy proxy calls `betterAuth()`
+ * fresh on first use inside its own closure (see `src/server/index.ts`), so
+ * two calls here are two independently-constructed `Auth` objects even when
+ * (as here) they resolve through the same imported `rawOpensaasContext`
+ * module — itself just the standard Prisma-connection-pooling shape a real
+ * app would also share across requests. What distinguishes this from
+ * in-memory rate-limit storage is that each `betterAuth()` instance keeps no
+ * limiter state of its own — every read/write round-trips through Prisma to
+ * the shared on-disk table, which is exactly the property under test.
+ */
+async function createAuthInstanceForProject(dir: string) {
+  // The config's `prismaClientConstructor` reads `process.env.DATABASE_URL` at
+  // runtime (unlike the `generate`/`db push` subprocesses, which received it
+  // via their own `env`). An absolute path avoids it resolving relative to
+  // the test process's cwd instead of the temp project dir.
+  process.env.DATABASE_URL = `file:${path.join(dir, 'dev.db')}`
+
+  // `@vite-ignore` suppresses Vite's static analysis of this computed,
+  // external (outside the package root) specifier — it isn't something Vite
+  // could usefully pre-bundle anyway.
+  const config = (
+    (await import(/* @vite-ignore */ pathToFileURL(path.join(dir, 'opensaas.config.ts')).href)) as {
+      default: OpenSaasConfig | Promise<OpenSaasConfig>
+    }
+  ).default
+  const { rawOpensaasContext } = (await import(
+    /* @vite-ignore */ pathToFileURL(path.join(dir, '.opensaas/context.ts')).href
+  )) as { rawOpensaasContext: Promise<AccessContext> }
+
+  const resolvedContext = await rawOpensaasContext
+
+  return { auth: createAuth(config, resolvedContext), context: resolvedContext }
+}
+
+/** Unlink the borrowed node_modules symlink (never recurse into/delete the real one) and remove the temp root. */
+async function cleanupProject(dir: string): Promise<void> {
+  // The generated `.opensaas/context.ts` caches its Prisma client on
+  // `globalThis.prisma` outside `NODE_ENV === 'production'` (the standard
+  // dev-mode HMR pattern, so a hot reload doesn't open a fresh connection
+  // every time). That's process-wide, not per-module — so the NEXT temp
+  // project created in this same test process would otherwise inherit THIS
+  // one's already-cached client, silently pointed at a temp dir this
+  // function is about to delete. Clear it so each project's own
+  // `prismaClientConstructor` runs fresh.
+  delete (globalThis as { prisma?: unknown }).prisma
+
+  const linkPath = path.join(dir, 'node_modules')
+  if (existsSync(linkPath)) {
+    await fsp.unlink(linkPath)
+  }
+  await fsp.rm(path.dirname(dir), { recursive: true, force: true })
+}
+
+describe.skipIf(!prerequisitesPresent)(
+  'database-backed rate limiter — live end-to-end (issue #909)',
+  () => {
+    it('rejects requests once the count exceeds max within the window, against a real generated RateLimit table', async () => {
+      const dir = await setupProject(60, 3)
+      try {
+        const { auth, context } = await createAuthInstanceForProject(dir)
+        const ip = '203.0.113.10'
+
+        const statuses: number[] = []
+        for (let i = 0; i < 5; i++) {
+          const res = await auth.handler(sessionRequest(ip))
+          statuses.push(res.status)
+        }
+
+        // First `max` (3) requests succeed, everything past it is rejected.
+        expect(statuses.slice(0, 3)).toEqual([200, 200, 200])
+        expect(statuses.slice(3)).toEqual([429, 429])
+        await context.prisma.$disconnect()
+      } finally {
+        await cleanupProject(dir)
+      }
+    }, 120_000)
+
+    it('persists the counter across two separately-constructed auth instances sharing the database', async () => {
+      const dir = await setupProject(60, 3)
+      try {
+        const ip = '198.51.100.20'
+
+        // Two independently-constructed betterAuth() instances (via two
+        // separate createAuth() lazy proxies), sharing one sqlite file —
+        // the property in-memory storage does not have.
+        const { auth: authA } = await createAuthInstanceForProject(dir)
+        const { auth: authB, context } = await createAuthInstanceForProject(dir)
+
+        expect((await authA.handler(sessionRequest(ip))).status).toBe(200)
+        expect((await authA.handler(sessionRequest(ip))).status).toBe(200)
+        expect((await authA.handler(sessionRequest(ip))).status).toBe(200)
+
+        // Instance B, constructed fresh and never having handled a request
+        // for this IP, must see A's persisted counter via the database and
+        // reject — proof the limiter state lives in the DB, not in-process.
+        expect((await authB.handler(sessionRequest(ip))).status).toBe(429)
+        await context.prisma.$disconnect()
+      } finally {
+        await cleanupProject(dir)
+      }
+    }, 120_000)
+  },
+)
+
+// Surface, in a normal unit run, why this guard was skipped.
+describe.runIf(!prerequisitesPresent)('database-backed rate limiter e2e (skipped)', () => {
+  it('runs only in the e2e job (set RUN_RATE_LIMIT_E2E=1 after install + build)', () => {
+    expect(prerequisitesPresent).toBe(false)
+  })
+
+  afterAll(() => {
+    if (!guardEnabled) return
+    // The guard is opted in but its build/toolchain prerequisites are
+    // missing — surface why, mirroring the scaffold guard's message.
+    console.warn(
+      '[rate-limit-e2e] RUN_RATE_LIMIT_E2E=1 was set but prerequisites are missing. ' +
+        'Run `pnpm install && pnpm build` (and ensure examples/starter-auth has been installed) first.',
+    )
+  })
+})