@opensaas/stack-auth 0.36.0 → 0.38.0

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

@@ -2,13 +2,15 @@
  * Pure `better-auth config → Auth lists` derivation.
  *
  * This module is intentionally free of side effects and plugin/runtime
- * concerns: given the resolved better-auth model config (per-model `modelName`
- * and `fields` column maps) plus any custom User fields, it produces the four
- * OpenSaaS Auth lists (user/session/account/verification) with:
+ * concerns: given the resolved better-auth model config (per-model `modelName`,
+ * `tableName`, and `fields` column maps) plus any custom User fields, it
+ * produces the four OpenSaaS Auth lists (user/session/account/verification)
+ * with:
  *
  *  - list keys taken from each model's `modelName`
- *  - a table `@@map` (list-level `db.map`) when the key differs from the
- *    default better-auth model name
+ *  - a table `@@map` (list-level `db.map`) taken from each model's resolved
+ *    `tableName` — independent of `modelName`, so a renamed list key can still
+ *    adopt a differently-named live table
  *  - field-level `@map` (`db.map`) for any better-auth field → column override
  *  - relationship refs between the auth lists wired to the *derived* keys
  *    (e.g. `Session.user → AuthUser.sessions`)
@@ -31,17 +33,6 @@ import type { RelationshipField } from '@opensaas/stack-core/fields'
 import type { ExtendUserListConfig } from '../lists/index.js'
 import type { AuthAccessConfig, NormalizedAuthModelConfig, NormalizedAuthModels } from './types.js'
 
-/**
- * Default better-auth model names — used to decide whether a `@@map` is needed
- * (only when the configured `modelName` differs from the default).
- */
-const DEFAULT_MODEL_NAMES = {
-  user: 'User',
-  session: 'Session',
-  account: 'Account',
-  verification: 'Verification',
-} as const
-
 /**
  * The derived Auth list set together with the keys each list was placed under.
  * Keys are surfaced separately so callers (plugin add-vs-extend logic, runtime
@@ -71,24 +62,24 @@ export type DerivedAuthLists = {
  * Auth list must opt back in so the generated models keep those columns and
  * better-auth keeps working.
  *
- * When the developer renames the model (e.g. `modelName: 'AuthUser'`), we also
- * pin the physical table name to that model name via `@@map("AuthUser")` so the
- * generated list adopts the developer's live table exactly. When a `schema` is
- * configured (plugin-level or per-model), the list is placed in that Postgres
- * schema via `@@schema(...)`.
+ * The physical table name (`@@map`) comes from the model's resolved
+ * `tableName` — independent of the list key/`modelName` — so a renamed list
+ * key can still adopt a differently-named live table (e.g. better-auth's own
+ * 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 `modelName`/`schema` overrides we emit only `timestamps: true`,
+ * With no `tableName`/`schema` overrides we emit only `timestamps: true`,
  * leaving the default `User`/`Session`/... table/schema output unchanged.
  */
-function listDb(
-  model: NormalizedAuthModelConfig,
-  defaultModelName: string,
-): { timestamps: true; map?: string; schema?: string } {
-  const map = model.modelName !== defaultModelName ? model.modelName : undefined
+function listDb(model: NormalizedAuthModelConfig): {
+  timestamps: true
+  map?: string
+  schema?: string
+} {
   const schema = model.schema
   return {
     timestamps: true,
-    ...(map !== undefined ? { map } : {}),
+    ...(model.tableName !== undefined ? { map: model.tableName } : {}),
     ...(schema !== undefined ? { schema } : {}),
   }
 }
@@ -110,14 +101,18 @@ function fieldDb(fieldName: string, fields: Record<string, string>): { map: stri
  * Build the `db` config for a `user` relationship (`Session.user` /
  * `Account.user`), honouring a `userId` column override from the better-auth
  * `fields` map and mirroring better-auth's own FK shape: no separate FK index
- * — the index is applied at the field level via `isIndexed: false` — and
- * `onDelete: Cascade`, so a generated Auth schema diffs clean against a live
- * better-auth database on both dimensions instead of showing a spurious index
- * drop and a referential-action change (issue #679).
+ * — the index is applied at the field level via `isIndexed: false` —
+ * `onDelete: Cascade`, and a required (non-nullable) foreign key, since
+ * better-auth's adapter always writes a `userId` on every session/account row
+ * it creates. This means a generated Auth schema diffs clean against a live
+ * better-auth database on all three dimensions instead of showing a spurious
+ * index drop, a referential-action change, and a `DROP NOT NULL` (issues #679,
+ * #863).
  */
 function userRelationshipDb(fields: Record<string, string>): NonNullable<RelationshipField['db']> {
   const column = fields.userId
   return {
+    isNullable: false,
     ...(column ? { foreignKey: { map: column } } : {}),
     extendPrismaSchema: ({ fkLine, relationLine }) => ({
       fkLine,
@@ -161,7 +156,7 @@ function createUserList(
       // Custom fields from user config
       ...(userConfig.fields || {}),
     },
-    db: listDb(model, DEFAULT_MODEL_NAMES.user),
+    db: listDb(model),
     access: userConfig.access || access,
     hooks: userConfig.hooks,
   })
@@ -187,7 +182,9 @@ function createSessionList(
         isIndexed: 'unique',
         db: fieldDb('token', f),
       }),
-      expiresAt: timestamp({ db: fieldDb('expiresAt', f) }),
+      expiresAt: timestamp({
+        db: { isNullable: false, ...fieldDb('expiresAt', f) },
+      }),
       ipAddress: text({ db: fieldDb('ipAddress', f) }),
       userAgent: text({ db: fieldDb('userAgent', f) }),
       user: relationship({
@@ -196,7 +193,7 @@ function createSessionList(
         db: userRelationshipDb(f),
       }),
     },
-    db: listDb(model, DEFAULT_MODEL_NAMES.session),
+    db: listDb(model),
     access,
   })
 }
@@ -231,7 +228,7 @@ function createAccountList(
       idToken: text({ db: fieldDb('idToken', f) }),
       password: text({ db: fieldDb('password', f) }),
     },
-    db: listDb(model, DEFAULT_MODEL_NAMES.account),
+    db: listDb(model),
     access,
   })
 }
@@ -252,9 +249,11 @@ function createVerificationList(
     fields: {
       identifier: text({ validation: { isRequired: true }, db: fieldDb('identifier', f) }),
       value: text({ validation: { isRequired: true }, db: fieldDb('value', f) }),
-      expiresAt: timestamp({ db: fieldDb('expiresAt', f) }),
+      expiresAt: timestamp({
+        db: { isNullable: false, ...fieldDb('expiresAt', f) },
+      }),
     },
-    db: listDb(model, DEFAULT_MODEL_NAMES.verification),
+    db: listDb(model),
     access,
   })
 }

package/src/config/index.ts

@@ -7,6 +7,7 @@ import type {
   EmailPasswordConfig,
   EmailVerificationConfig,
   PasswordResetConfig,
+  SendAuthEmail,
 } from './types.js'
 
 /**
@@ -26,14 +27,24 @@ const DEFAULT_MODEL_NAMES = {
  * falling back to the better-auth default model name and an empty column map.
  * The model's Postgres schema is the per-model `schema` override when present,
  * otherwise the plugin-level `schema` default (or `undefined` for `public`).
+ *
+ * `tableName` defaults to today's behaviour when not explicitly set: it
+ * follows `modelName` when that differs from the better-auth default (so a
+ * renamed list still pins its table via `@@map`), otherwise it stays unset.
+ * An explicit `tableName` is independent of `modelName` — it lets a renamed
+ * list key adopt a differently-named live table (e.g. better-auth's own
+ * default lowercase table names).
  */
 function normalizeModelConfig(
   config: AuthModelConfig | undefined,
   defaultModelName: string,
   defaultSchema: string | undefined,
 ): NormalizedAuthModelConfig {
+  const modelName = config?.modelName || defaultModelName
+  const tableName = config?.tableName ?? (modelName !== defaultModelName ? modelName : undefined)
   return {
-    modelName: config?.modelName || defaultModelName,
+    modelName,
+    tableName,
     fields: config?.fields || {},
     schema: config?.schema ?? defaultSchema,
   }
@@ -58,6 +69,21 @@ function normalizeAuthModels(config: AuthConfig): NormalizedAuthModels {
   }
 }
 
+/**
+ * Default `sendResetPassword`/`sendVerificationEmail` — logs to console
+ * instead of sending, matching the pre-existing "no sendEmail configured"
+ * behavior for apps that haven't wired a real email provider yet.
+ */
+function defaultSendAuthEmail(kind: 'password reset' | 'verification'): SendAuthEmail {
+  return async ({ user, url }) => {
+    console.log(
+      `[Auth] ${kind[0].toUpperCase()}${kind.slice(1)} email not sent (no callback configured):`,
+    )
+    console.log(`To: ${user.email}`)
+    console.log(`URL: ${url}`)
+  }
+}
+
 /**
  * Normalize auth configuration with defaults
  */
@@ -69,8 +95,16 @@ export function normalizeAuthConfig(config: AuthConfig): NormalizedAuthConfig {
         minPasswordLength: (config.emailAndPassword as EmailPasswordConfig).minPasswordLength ?? 8,
         requireConfirmation:
           (config.emailAndPassword as EmailPasswordConfig).requireConfirmation ?? true,
+        sendResetPassword:
+          (config.emailAndPassword as EmailPasswordConfig).sendResetPassword ??
+          defaultSendAuthEmail('password reset'),
+      }
+    : {
+        enabled: false as const,
+        minPasswordLength: 8,
+        requireConfirmation: true,
+        sendResetPassword: defaultSendAuthEmail('password reset'),
       }
-    : { enabled: false as const, minPasswordLength: 8, requireConfirmation: true }
 
   // Email verification defaults
   const emailVerification = config.emailVerification?.enabled
@@ -79,8 +113,16 @@ export function normalizeAuthConfig(config: AuthConfig): NormalizedAuthConfig {
         sendOnSignUp: (config.emailVerification as EmailVerificationConfig).sendOnSignUp ?? true,
         tokenExpiration:
           (config.emailVerification as EmailVerificationConfig).tokenExpiration ?? 86400,
+        sendVerificationEmail:
+          (config.emailVerification as EmailVerificationConfig).sendVerificationEmail ??
+          defaultSendAuthEmail('verification'),
+      }
+    : {
+        enabled: false as const,
+        sendOnSignUp: true,
+        tokenExpiration: 86400,
+        sendVerificationEmail: defaultSendAuthEmail('verification'),
       }
-    : { enabled: false as const, sendOnSignUp: true, tokenExpiration: 86400 }
 
   // Password reset defaults
   const passwordReset = config.passwordReset?.enabled
@@ -93,7 +135,7 @@ export function normalizeAuthConfig(config: AuthConfig): NormalizedAuthConfig {
   // Session defaults
   const session = {
     expiresIn: config.session?.expiresIn || 604800, // 7 days
-    updateAge: config.session?.updateAge ?? true,
+    updateAge: config.session?.updateAge ?? 86400, // 1 day, matching better-auth's own default
   }
 
   // Session fields defaults
@@ -114,16 +156,9 @@ export function normalizeAuthConfig(config: AuthConfig): NormalizedAuthConfig {
     sessionFields,
     extendUserList: config.extendUserList || {},
     access: config.access || {},
-    sendEmail:
-      config.sendEmail ||
-      (async ({ to, subject, html }) => {
-        console.log('[Auth] Email not sent (no sendEmail configured):')
-        console.log(`To: ${to}`)
-        console.log(`Subject: ${subject}`)
-        console.log(`Body: ${html}`)
-      }),
     betterAuthPlugins: config.betterAuthPlugins || [],
     rateLimit: config.rateLimit,
+    betterAuthOptions: config.betterAuthOptions || {},
   }
 }
 

package/src/config/plugin.ts

@@ -62,34 +62,13 @@ export function authPlugin(config: AuthConfig): Plugin {
         verification: normalized.models.verification.modelName,
       }
 
-      // Extract additional lists from Better Auth plugins
-      for (const plugin of normalized.betterAuthPlugins) {
-        if (plugin && typeof plugin === 'object' && 'schema' in plugin) {
-          // Plugin has schema property - convert to OpenSaaS lists
-          const pluginSchema = plugin.schema
-          const pluginLists = convertBetterAuthSchema(pluginSchema, baseModelKeys)
-
-          // Add or extend lists from plugin
-          for (const [listName, listConfig] of Object.entries(pluginLists)) {
-            if (context.config.lists[listName]) {
-              // List already exists — merge fields/hooks/mcp in only. Access
-              // control belongs to whoever owns the list; per ADR-0013 an
-              // extension must never carry operation-level access for a
-              // pre-existing list (the plugin engine throws if it does).
-              context.extendList(listName, {
-                fields: listConfig.fields,
-                hooks: listConfig.hooks,
-                mcp: listConfig.mcp,
-              })
-            } else {
-              // List doesn't exist, add it
-              context.addList(listName, listConfig)
-            }
-          }
-        }
-      }
-
-      // Add all auth lists.
+      // Add all auth lists FIRST, before any better-auth plugin schema
+      // extension is processed. This must happen before the betterAuthPlugins
+      // loop below so a base-model extension (e.g. a plugin's `schema: {
+      // user: { fields: … } }`) always finds the real derived list already
+      // registered under its key and takes the merge (`extendList`) path
+      // against it — instead of pre-empting that key with a bare
+      // `list({ fields })` that carries no `db`/`access` (see #861).
       //
       // The plugin only ever touches its OWN derived keys. When a developer
       // renames the auth user model (e.g. user.modelName: 'AuthUser'), the
@@ -115,6 +94,39 @@ export function authPlugin(config: AuthConfig): Plugin {
         }
       }
 
+      // Extract additional lists from Better Auth plugins. Because the auth
+      // lists above are already registered, a schema extension of a base
+      // model (user/session/account/verification) always finds its resolved
+      // key occupied by the real derived list and merges via `extendList` —
+      // its `db`/`access` are preserved. Non-base plugin tables (e.g.
+      // `oauth_application`, `passkey`) still register as new lists via
+      // `addList`, same as before.
+      for (const plugin of normalized.betterAuthPlugins) {
+        if (plugin && typeof plugin === 'object' && plugin.schema) {
+          // Plugin has schema property - convert to OpenSaaS lists
+          const pluginSchema = plugin.schema
+          const pluginLists = convertBetterAuthSchema(pluginSchema, baseModelKeys)
+
+          // Add or extend lists from plugin
+          for (const [listName, listConfig] of Object.entries(pluginLists)) {
+            if (context.config.lists[listName]) {
+              // List already exists — merge fields/hooks/mcp in only. Access
+              // control belongs to whoever owns the list; per ADR-0013 an
+              // extension must never carry operation-level access for a
+              // pre-existing list (the plugin engine throws if it does).
+              context.extendList(listName, {
+                fields: listConfig.fields,
+                hooks: listConfig.hooks,
+                mcp: listConfig.mcp,
+              })
+            } else {
+              // List doesn't exist, add it
+              context.addList(listName, listConfig)
+            }
+          }
+        }
+      }
+
       // Store auth config for runtime access
       // Access at runtime via: config._pluginData.auth
       context.setPluginData<NormalizedAuthConfig>('auth', normalized)

package/src/config/types.ts

@@ -1,6 +1,18 @@
 import type { ListConfig } from '@opensaas/stack-core'
+import type { BetterAuthOptions, BetterAuthPlugin, User } from 'better-auth'
 import type { ExtendUserListConfig } from '../lists/index.js'
 
+/**
+ * better-auth's own callback shape for `sendVerificationEmail`/
+ * `sendResetPassword` — `data` is exactly what better-auth passes (no stack
+ * abstraction layered on top), and `request` is the raw request that
+ * triggered it.
+ */
+export type SendAuthEmail = (
+  data: { user: User; url: string; token: string },
+  request?: Request,
+) => Promise<void>
+
 /**
  * OAuth provider configuration
  */
@@ -32,10 +44,36 @@ export type EmailPasswordConfig = {
    */
   minPasswordLength?: number
   /**
-   * Require password confirmation
+   * Require password confirmation (a second "confirm password" field).
+   *
+   * There is no better-auth server-side equivalent — this is purely a UI
+   * concern. `createAuth()` does not read it. Pass it directly to the
+   * pre-built forms instead: `<SignUpForm requirePasswordConfirmation={...} />`
+   * / `<ResetPasswordForm requirePasswordConfirmation={...} />` (both default
+   * to `true`). Setting it here has no effect and `createAuth()` warns if it
+   * is configured.
+   *
    * @default true
    */
   requireConfirmation?: boolean
+  /**
+   * Send a password reset email. Passed straight through to better-auth's own
+   * `emailAndPassword.sendResetPassword` — the stack does not wrap or
+   * reshape it. If not provided, reset emails are logged to console instead
+   * of sent.
+   *
+   * @example
+   * ```typescript
+   * sendResetPassword: async ({ user, url }) => {
+   *   await resend.emails.send({
+   *     to: user.email,
+   *     subject: 'Reset your password',
+   *     html: `<a href="${url}">Reset your password</a>`,
+   *   })
+   * }
+   * ```
+   */
+  sendResetPassword?: SendAuthEmail
 }
 
 /**
@@ -53,6 +91,24 @@ export type EmailVerificationConfig = {
    * @default 86400 (24 hours)
    */
   tokenExpiration?: number
+  /**
+   * Send a verification email. Passed straight through to better-auth's own
+   * `emailVerification.sendVerificationEmail` — the stack does not wrap or
+   * reshape it. If not provided, verification emails are logged to console
+   * instead of sent.
+   *
+   * @example
+   * ```typescript
+   * sendVerificationEmail: async ({ user, url }) => {
+   *   await resend.emails.send({
+   *     to: user.email,
+   *     subject: 'Verify your email',
+   *     html: `<a href="${url}">Verify your email</a>`,
+   *   })
+   * }
+   * ```
+   */
+  sendVerificationEmail?: SendAuthEmail
 }
 
 /**
@@ -77,10 +133,12 @@ export type SessionConfig = {
    */
   expiresIn?: number
   /**
-   * Update session expiration on each request
-   * @default true
+   * How often the session should be refreshed, in seconds. Passed straight
+   * through to better-auth's own `session.updateAge`. Set `false` to disable
+   * refresh entirely (the session expiry is then fixed at creation time).
+   * @default 86400 (1 day, matching better-auth's own default)
    */
-  updateAge?: boolean
+  updateAge?: number | false
 }
 
 /**
@@ -150,10 +208,30 @@ export type AuthAccessConfig = {
 export type AuthModelConfig = {
   /**
    * The table/list name for this model.
-   * Becomes the OpenSaaS list key (and Prisma model name) and the table `@@map`.
+   * Becomes the OpenSaaS list key and Prisma model name.
    * @default the default better-auth model name (e.g. 'User', 'Session')
    */
   modelName?: string
+  /**
+   * The physical database table name for this model, independent of
+   * `modelName`. Generates a `@@map("...")` on the derived list.
+   *
+   * Lets a renamed list key (e.g. `modelName: 'AuthUser'`, to avoid colliding
+   * with an app's own domain `User`) still adopt a live table under a
+   * different name — most commonly better-auth's own default lowercase
+   * table names (`user`, `session`, `account`, `verification`).
+   *
+   * @default `modelName` when it differs from the better-auth default model
+   *   name, otherwise unset (no `@@map`) — i.e. today's behaviour when this
+   *   option is not set.
+   *
+   * @example
+   * ```typescript
+   * // List key AuthUser, but the live table is still called `user`.
+   * user: { modelName: 'AuthUser', tableName: 'user' }
+   * ```
+   */
+  tableName?: string
   /**
    * Map better-auth field names to database column names.
    * Each entry generates a `@map("column")` on the derived field.
@@ -259,8 +337,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
@@ -303,19 +394,6 @@ export type AuthConfig = {
    */
   access?: AuthAccessConfig
 
-  /**
-   * Custom email sending function for verification and password reset
-   * If not provided, emails will be logged to console
-   *
-   * @example
-   * ```typescript
-   * sendEmail: async ({ to, subject, html }) => {
-   *   await resend.emails.send({ to, subject, html })
-   * }
-   * ```
-   */
-  sendEmail?: (params: { to: string; subject: string; html: string }) => Promise<void>
-
   /**
    * Additional Better Auth plugins to enable
    * Allows integrating any Better Auth plugin (MCP, 2FA, etc.)
@@ -329,8 +407,7 @@ 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
@@ -364,17 +441,58 @@ export type AuthConfig = {
      */
     max?: number
   }
+
+  /**
+   * Escape hatch for better-auth options the stack doesn't model — typed as
+   * better-auth's own `BetterAuthOptions` so it stays in step with
+   * better-auth's surface without the stack re-declaring it. Deep-merged into
+   * the options `createAuth()` builds, applied LAST: a plain-object value at a
+   * given key merges recursively with whatever the stack already set there
+   * (so e.g. `session: { cookieCache: {...} }` adds alongside the stack's own
+   * `session.expiresIn`/`updateAge` rather than clobbering them); any other
+   * value (including arrays) replaces the stack's value outright. On a genuine
+   * key collision, this option wins.
+   *
+   * `database` and `plugins` are rejected — they're already the dedicated
+   * seams (the stack's `db` config, and `betterAuthPlugins` respectively) and
+   * accepting them here would create two unranked ways to set the same thing.
+   * So is `additionalFields` under `user`/`session`/`account`/`verification` —
+   * it has schema consequences (new columns) that a passthrough can't also
+   * apply to the generated Prisma schema; add fields to the derived list
+   * instead (`extendUserList` for the user model, or declare the list
+   * yourself for the others — see `packages/auth/CLAUDE.md`).
+   *
+   * The same options object is available standalone via
+   * `buildBetterAuthOptions()` (`@opensaas/stack-auth/server`) for apps that
+   * still need to hand-wire their own `betterAuth()` instance.
+   *
+   * @example
+   * ```typescript
+   * authPlugin({
+   *   betterAuthOptions: {
+   *     databaseHooks: { user: { create: { after: syncDomainUser } } },
+   *     session: { cookieCache: { enabled: true, maxAge: 300 } },
+   *     verification: { storeIdentifier: 'hashed' },
+   *     baseURL: process.env.BETTER_AUTH_URL,
+   *   },
+   * })
+   * ```
+   */
+  betterAuthOptions?: Partial<BetterAuthOptions>
 }
 
 /**
  * Resolved per-model auth configuration after normalization.
  * Always carries a concrete `modelName` (the developer's override or the
- * better-auth default) and a (possibly empty) `fields` column map. `schema`
- * carries the resolved Postgres schema for the model (per-model override, else
- * the plugin-level schema, else `undefined` for the default `public` schema).
+ * better-auth default) and a (possibly empty) `fields` column map. `tableName`
+ * is the resolved physical table name — `undefined` means no `@@map` is
+ * emitted (the list key doubles as the table name). `schema` carries the
+ * resolved Postgres schema for the model (per-model override, else the
+ * plugin-level schema, else `undefined` for the default `public` schema).
  */
 export type NormalizedAuthModelConfig = {
   modelName: string
+  tableName?: string
   fields: Record<string, string>
   schema?: string
 }
@@ -422,8 +540,7 @@ 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

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