@opensaas/stack-auth 0.37.0 → 0.39.0

package/src/config/derive-auth-lists.ts

@@ -27,7 +27,14 @@
  */
 
 import { list } from '@opensaas/stack-core'
-import { text, timestamp, checkbox, relationship } from '@opensaas/stack-core/fields'
+import {
+  text,
+  timestamp,
+  checkbox,
+  integer,
+  bigInt,
+  relationship,
+} from '@opensaas/stack-core/fields'
 import type { ListConfig } from '@opensaas/stack-core'
 import type { RelationshipField } from '@opensaas/stack-core/fields'
 import type { ExtendUserListConfig } from '../lists/index.js'
@@ -45,6 +52,8 @@ export type DerivedAuthLists = {
     session: string
     account: string
     verification: string
+    /** Only present when a `RateLimit` list was derived (`rateLimit.storage === 'database'`). */
+    rateLimit?: string
   }
   /** The derived list configs, keyed by their derived list keys. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
@@ -55,12 +64,12 @@ export type DerivedAuthLists = {
  * Build the list-level `db` config (`timestamps` + `@@map` + `@@schema`) for a
  * derived list.
  *
- * Always opts the list into auto-timestamps (`timestamps: true`). better-auth's
- * adapter writes `createdAt`/`updatedAt` on every auth row and the schema
- * converter returns `null` for those columns (it assumes the generator injects
- * them). Now that auto-timestamps are OFF by default (ADR-0004), each derived
- * Auth list must opt back in so the generated models keep those columns and
- * better-auth keeps working.
+ * `timestamps` is a per-model input rather than hardcoded: better-auth's
+ * adapter writes `createdAt`/`updatedAt` on every user/session/account/
+ * verification row (and the schema converter returns `null` for those columns,
+ * assuming the generator injects them), so those four opt back into
+ * auto-timestamps now that they're OFF by default (ADR-0004). The `RateLimit`
+ * model has neither column in better-auth's own schema, so it passes `false`.
  *
  * The physical table name (`@@map`) comes from the model's resolved
  * `tableName` — independent of the list key/`modelName` — so a renamed list
@@ -68,17 +77,17 @@ export type DerivedAuthLists = {
  * default lowercase table names). When a `schema` is configured (plugin-level
  * or per-model), the list is placed in that Postgres schema via `@@schema(...)`.
  *
- * With no `tableName`/`schema` overrides we emit only `timestamps: true`,
- * leaving the default `User`/`Session`/... table/schema output unchanged.
+ * With no `tableName`/`schema` overrides and `timestamps: true` we emit only
+ * `{ timestamps: true }`, leaving the default `User`/`Session`/... output
+ * unchanged.
  */
-function listDb(model: NormalizedAuthModelConfig): {
-  timestamps: true
-  map?: string
-  schema?: string
-} {
+function listDb(
+  model: NormalizedAuthModelConfig,
+  timestamps: boolean,
+): { timestamps?: true; map?: string; schema?: string } {
   const schema = model.schema
   return {
-    timestamps: true,
+    ...(timestamps ? { timestamps: true as const } : {}),
     ...(model.tableName !== undefined ? { map: model.tableName } : {}),
     ...(schema !== undefined ? { schema } : {}),
   }
@@ -156,7 +165,7 @@ function createUserList(
       // Custom fields from user config
       ...(userConfig.fields || {}),
     },
-    db: listDb(model),
+    db: listDb(model, true),
     access: userConfig.access || access,
     hooks: userConfig.hooks,
   })
@@ -193,7 +202,7 @@ function createSessionList(
         db: userRelationshipDb(f),
       }),
     },
-    db: listDb(model),
+    db: listDb(model, true),
     access,
   })
 }
@@ -228,7 +237,7 @@ function createAccountList(
       idToken: text({ db: fieldDb('idToken', f) }),
       password: text({ db: fieldDb('password', f) }),
     },
-    db: listDb(model),
+    db: listDb(model, true),
     access,
   })
 }
@@ -253,7 +262,51 @@ function createVerificationList(
         db: { isNullable: false, ...fieldDb('expiresAt', f) },
       }),
     },
-    db: listDb(model),
+    db: listDb(model, true),
+    access,
+  })
+}
+
+/**
+ * Create the Auth rate-limit list, present only when `rateLimit.storage ===
+ * 'database'` derives a `rateLimit` model. Mirrors better-auth's own
+ * `rateLimit` table exactly (`getAuthTables` in `@better-auth/core`, verified
+ * against better-auth@1.6.25): `key` (unique — load-bearing, not cosmetic,
+ * since the limiter races concurrent requests into a create and relies on the
+ * resulting constraint violation to serialise them), `count`, and
+ * `lastRequest` (a millisecond epoch, hence `bigInt()` rather than
+ * `integer()`, which would overflow). None of the three columns carries a
+ * Prisma default — the limiter supplies `lastRequest` explicitly on every
+ * create/update, and an adopted live table has no default to match. No
+ * `createdAt`/`updatedAt` either (see `listDb`'s `timestamps` argument):
+ * better-auth's own rate-limit table has neither column.
+ *
+ * Per ADR-0013, the plugin ships no permissive access default — closed unless
+ * the application supplies `access.rateLimit`.
+ */
+function createRateLimitList(
+  model: NormalizedAuthModelConfig,
+  access: AuthAccessConfig['rateLimit'],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+): ListConfig<any> {
+  const f = model.fields
+  return list({
+    fields: {
+      key: text({
+        validation: { isRequired: true },
+        isIndexed: 'unique',
+        db: fieldDb('key', f),
+      }),
+      count: integer({
+        validation: { isRequired: true },
+        db: { isNullable: false, ...fieldDb('count', f) },
+      }),
+      lastRequest: bigInt({
+        validation: { isRequired: true },
+        db: { isNullable: false, ...fieldDb('lastRequest', f) },
+      }),
+    },
+    db: listDb(model, false),
     access,
   })
 }
@@ -267,21 +320,25 @@ function createVerificationList(
  * for the user list specifically, `userConfig.access` (`extendUserList.access`,
  * which takes precedence — see {@link AuthAccessConfig}).
  *
+ * A fifth `RateLimit` list is included only when `models.rateLimit` is
+ * present (i.e. `rateLimit.storage === 'database'`).
+ *
  * @param models - Resolved better-auth per-model config (modelName + field column maps)
  * @param userConfig - Extra User-list fields/access/hooks supplied via `extendUserList`
  * @param accessConfig - App-authored access for each Auth list, keyed by better-auth model name
- * @returns The derived list keys and the four Auth list configs keyed by those keys
+ * @returns The derived list keys and the Auth list configs keyed by those keys
  */
 export function deriveAuthLists(
   models: NormalizedAuthModels,
   userConfig: ExtendUserListConfig = {},
   accessConfig: AuthAccessConfig = {},
 ): DerivedAuthLists {
-  const keys = {
+  const keys: DerivedAuthLists['keys'] = {
     user: models.user.modelName,
     session: models.session.modelName,
     account: models.account.modelName,
     verification: models.verification.modelName,
+    ...(models.rateLimit ? { rateLimit: models.rateLimit.modelName } : {}),
   }
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
@@ -292,5 +349,9 @@ export function deriveAuthLists(
     [keys.verification]: createVerificationList(models.verification, accessConfig.verification),
   }
 
+  if (models.rateLimit && keys.rateLimit) {
+    lists[keys.rateLimit] = createRateLimitList(models.rateLimit, accessConfig.rateLimit)
+  }
+
   return { keys, lists }
 }

package/src/config/index.ts

@@ -13,13 +13,15 @@ import type {
 /**
  * Default better-auth model names. Used when the developer does not override
  * `modelName`, preserving the historical `User`/`Session`/`Account`/`Verification`
- * keys exactly.
+ * keys exactly. `rateLimit` only applies when `rateLimit.storage: 'database'`
+ * derives the fifth Auth list.
  */
 const DEFAULT_MODEL_NAMES = {
   user: 'User',
   session: 'Session',
   account: 'Account',
   verification: 'Verification',
+  rateLimit: 'RateLimit',
 } as const
 
 /**
@@ -51,13 +53,14 @@ function normalizeModelConfig(
 }
 
 /**
- * Resolve the better-auth model config for all four auth models.
- * `defaultSchema` is the plugin-level `schema` applied to every model unless a
- * per-model `schema` override is given.
+ * Resolve the better-auth model config for all four auth models, plus a fifth
+ * `rateLimit` model when `rateLimit.storage: 'database'` requires deriving
+ * the `RateLimit` list. `defaultSchema` is the plugin-level `schema` applied
+ * to every model unless a per-model `schema` override is given.
  */
 function normalizeAuthModels(config: AuthConfig): NormalizedAuthModels {
   const defaultSchema = config.schema
-  return {
+  const models: NormalizedAuthModels = {
     user: normalizeModelConfig(config.user, DEFAULT_MODEL_NAMES.user, defaultSchema),
     session: normalizeModelConfig(config.session, DEFAULT_MODEL_NAMES.session, defaultSchema),
     account: normalizeModelConfig(config.account, DEFAULT_MODEL_NAMES.account, defaultSchema),
@@ -67,6 +70,16 @@ function normalizeAuthModels(config: AuthConfig): NormalizedAuthModels {
       defaultSchema,
     ),
   }
+
+  if (config.rateLimit?.storage === 'database') {
+    models.rateLimit = normalizeModelConfig(
+      config.rateLimit,
+      DEFAULT_MODEL_NAMES.rateLimit,
+      defaultSchema,
+    )
+  }
+
+  return models
 }
 
 /**

package/src/config/plugin.ts

@@ -54,12 +54,17 @@ export function authPlugin(config: AuthConfig): Plugin {
       // (e.g. `user.modelName: 'AuthUser'`). A provider plugin's schema
       // extension of a base model (e.g. `user`) must resolve against this
       // remap too, so it lands on the adopted Auth list rather than a
-      // re-derived key that can collide with an unrelated host list.
+      // re-derived key that can collide with an unrelated host list. The
+      // `rateLimit` key is only present when `rateLimit.storage: 'database'`
+      // derived the fifth Auth list.
       const baseModelKeys = {
         user: normalized.models.user.modelName,
         session: normalized.models.session.modelName,
         account: normalized.models.account.modelName,
         verification: normalized.models.verification.modelName,
+        ...(normalized.models.rateLimit
+          ? { rateLimit: normalized.models.rateLimit.modelName }
+          : {}),
       }
 
       // Add all auth lists FIRST, before any better-auth plugin schema
@@ -102,7 +107,7 @@ export function authPlugin(config: AuthConfig): Plugin {
       // `oauth_application`, `passkey`) still register as new lists via
       // `addList`, same as before.
       for (const plugin of normalized.betterAuthPlugins) {
-        if (plugin && typeof plugin === 'object' && 'schema' in plugin) {
+        if (plugin && typeof plugin === 'object' && plugin.schema) {
           // Plugin has schema property - convert to OpenSaaS lists
           const pluginSchema = plugin.schema
           const pluginLists = convertBetterAuthSchema(pluginSchema, baseModelKeys)

package/src/config/types.ts

@@ -1,5 +1,5 @@
 import type { ListConfig } from '@opensaas/stack-core'
-import type { BetterAuthOptions, User } from 'better-auth'
+import type { BetterAuthOptions, BetterAuthPlugin, User } from 'better-auth'
 import type { ExtendUserListConfig } from '../lists/index.js'
 
 /**
@@ -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 = {
@@ -337,8 +345,21 @@ export type AuthConfig = {
   schema?: string
 
   /**
-   * Which fields to include in the session object
-   * This determines what data is available in access control functions
+   * Which fields to include in the session object passed to access control
+   * functions — a **flattened projection** of the resolved better-auth
+   * session, not the session's own shape. `getSessionFromAuth` (the
+   * implementation the scaffolded `getSession()` calls) resolves each name
+   * against a fixed precedence: a top-level key on the resolved session
+   * object, then the `user` object, then the `session` sub-object.
+   * `userId` is special-cased to the authenticated user's `id`.
+   *
+   * A `customSession` better-auth plugin fully replaces the resolved shape
+   * (it can nest fields anywhere, e.g. under its own custom key) —
+   * reconciling that shape against `sessionFields` is the application's job.
+   * A listed name that can't be resolved is omitted and warns once per
+   * field per process, naming what was checked, rather than silently
+   * becoming `undefined` in an access control function.
+   *
    * @default ['userId', 'email', 'name']
    *
    * @example
@@ -394,13 +415,28 @@ export type AuthConfig = {
    * ]
    * ```
    */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Better Auth plugin types are not exposed, must use any
-  betterAuthPlugins?: any[]
+  betterAuthPlugins?: BetterAuthPlugin[]
 
   /**
    * 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
@@ -414,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?: {
@@ -428,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
@@ -486,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 = {
@@ -494,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
 }
 
 /**
@@ -528,11 +582,11 @@ export type NormalizedAuthConfig = Required<
    * default (used to wire the datasource `schemas` array during generation).
    */
   schema?: string
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Better Auth plugin types are not exposed, must use any
-  betterAuthPlugins: any[]
+  betterAuthPlugins: BetterAuthPlugin[]
   rateLimit?: {
     enabled: boolean
     window?: number
     max?: number
+    storage?: 'memory' | 'database' | 'secondary-storage'
   }
 }

package/src/server/build-better-auth-options.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import { betterAuth } from 'better-auth'
+import type { BetterAuthOptions } from 'better-auth'
+import type { OpenSaasConfig, AccessContext } from '@opensaas/stack-core'
+import { emailOTP, customSession } from 'better-auth/plugins'
+import { buildBetterAuthOptions } from './index.js'
+
+// The literal shape a `customSession()` callback replaces the session with —
+// deliberately unlike better-auth's default `{ user, session }`, to prove the
+// builder's return type carries a custom shape through to `api.getSession()`.
+type AppSession = {
+  data: { allowAdminUI: boolean; subjectId: string }
+}
+
+type TestPlugins = [ReturnType<typeof emailOTP>, ReturnType<typeof customSession<AppSession>>]
+
+// `ReturnType<typeof buildBetterAuthOptions>` on the overloaded export itself
+// resolves against its last (generic) signature, not the call-site-selected
+// one — wrapping each call shape in its own ordinary function and reading
+// `ReturnType<typeof wrapper>` instead forces TS to resolve overloads exactly
+// as a real call site would.
+// 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 buildBetterAuthOptions(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 buildBetterAuthOptions(config, context, plugins)
+}
+
+type NoArgResult = Awaited<ReturnType<typeof callWithNoPlugins>>
+type BuiltOptionsWithPlugins = Awaited<ReturnType<typeof callWithPlugins>>
+type ConstructedAuth = ReturnType<typeof betterAuth<BuiltOptionsWithPlugins>>
+
+describe('buildBetterAuthOptions plugin-tuple typing', () => {
+  it('back-compat: the no-argument call still returns the widened BetterAuthOptions', () => {
+    expectTypeOf<NoArgResult>().toEqualTypeOf<BetterAuthOptions>()
+  })
+
+  it('preserves plugin-derived auth.api.* endpoints and a customSession shape', () => {
+    // emailOTP() endpoints exist on the constructed Auth's `api` — erased entirely
+    // when constructed from the widened `BetterAuthOptions` (see #876).
+    expectTypeOf<ConstructedAuth['api']['signInEmailOTP']>().not.toBeNever()
+    expectTypeOf<ConstructedAuth['api']['sendVerificationOTP']>().not.toBeNever()
+    expectTypeOf<ConstructedAuth['api']['checkVerificationOTP']>().not.toBeNever()
+
+    // customSession()'s replaced shape, not better-auth's default { user, session }.
+    type GetSessionReturn = Awaited<ReturnType<ConstructedAuth['api']['getSession']>>
+    expectTypeOf<GetSessionReturn>().toEqualTypeOf<AppSession | null>()
+  })
+})

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>>()
+  })
+})