@opensaas/stack-auth 0.36.0 → 0.37.0

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,7 +62,45 @@ export function authPlugin(config: AuthConfig): Plugin {
         verification: normalized.models.verification.modelName,
       }
 
-      // Extract additional lists from Better Auth plugins
+      // 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
+      // derived key is 'AuthUser' and an app's separate 'User' list is left
+      // untouched — the plugin never extends/overwrites a list it didn't
+      // derive. Extending only kicks in when an existing list shares the
+      // derived key (e.g. the default 'User'), which is the intended
+      // "merge auth fields into my User" behaviour.
+      for (const [listName, listConfig] of Object.entries(authLists)) {
+        if (context.config.lists[listName]) {
+          // A list already exists under this derived key — merge auth fields
+          // in only. Access control belongs to whoever owns the list (the
+          // application declared it first), so the plugin never forwards its
+          // own access here — see ADR-0013.
+          context.extendList(listName, {
+            fields: listConfig.fields,
+            hooks: listConfig.hooks,
+            mcp: listConfig.mcp,
+          })
+        } else {
+          // Otherwise, add the auth list
+          context.addList(listName, listConfig)
+        }
+      }
+
+      // 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' && 'schema' in plugin) {
           // Plugin has schema property - convert to OpenSaaS lists
@@ -89,32 +127,6 @@ export function authPlugin(config: AuthConfig): Plugin {
         }
       }
 
-      // Add all auth lists.
-      //
-      // The plugin only ever touches its OWN derived keys. When a developer
-      // renames the auth user model (e.g. user.modelName: 'AuthUser'), the
-      // derived key is 'AuthUser' and an app's separate 'User' list is left
-      // untouched — the plugin never extends/overwrites a list it didn't
-      // derive. Extending only kicks in when an existing list shares the
-      // derived key (e.g. the default 'User'), which is the intended
-      // "merge auth fields into my User" behaviour.
-      for (const [listName, listConfig] of Object.entries(authLists)) {
-        if (context.config.lists[listName]) {
-          // A list already exists under this derived key — merge auth fields
-          // in only. Access control belongs to whoever owns the list (the
-          // application declared it first), so the plugin never forwards its
-          // own access here — see ADR-0013.
-          context.extendList(listName, {
-            fields: listConfig.fields,
-            hooks: listConfig.hooks,
-            mcp: listConfig.mcp,
-          })
-        } else {
-          // Otherwise, add the auth list
-          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, 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.
@@ -303,19 +381,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.)
@@ -364,17 +429,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
 }