@opensaas/stack-auth 0.36.0 → 0.38.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @opensaas/stack-auth@0.36.0 build /home/runner/work/stack/stack/packages/auth
+> @opensaas/stack-auth@0.38.0 build /home/runner/work/stack/stack/packages/auth
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,151 @@
 # @opensaas/stack-auth
 
+## 0.38.0
+
+### Minor Changes
+
+- [#888](https://github.com/OpenSaasAU/stack/pull/888) [`8183827`](https://github.com/OpenSaasAU/stack/commit/8183827ec65d6cfd7153028f84057ab65dfdc7dd) Thanks [@borisno2](https://github.com/borisno2)! - `buildBetterAuthOptions()` and `createAuth()` now accept an optional third argument — your app's `betterAuthPlugins` array, the same array passed to `authPlugin({ betterAuthPlugins })` — so the returned options/`Auth` type carries the literal plugin tuple instead of the widened `BetterAuthOptions`/`Auth<BetterAuthOptions>`. Without this, `betterAuth()` constructed from the widened return loses plugin-derived `auth.api.*` endpoints (e.g. `emailOTP()`'s `signInEmailOTP`) and a `customSession()` plugin's replaced session shape.
+
+  ```typescript
+  export const appBetterAuthPlugins = [emailOTP({ sendVerificationOTP })] // same array passed to authPlugin({ betterAuthPlugins })
+
+  export const auth = betterAuth({
+    ...(await buildBetterAuthOptions(config, rawOpensaasContext, appBetterAuthPlugins)),
+  })
+  // auth.api.signInEmailOTP is now typed, and auth.api.getSession() returns your customSession() shape.
+  ```
+
+  The supplied tuple is for typing only — the plugin array used at runtime is always the one resolved from `authPlugin({ betterAuthPlugins })`. Passing a tuple that isn't the same plugin instances in the same order throws, naming the mismatch, so the two can't silently drift apart. Calling either function with no third argument is unchanged — same widened return type, same runtime options, fully backwards compatible.
+
+  Also, `AuthConfig`/`NormalizedAuthConfig`'s `betterAuthPlugins` field is now typed as better-auth's own `BetterAuthPlugin[]` instead of `any[]`.
+
+- [#889](https://github.com/OpenSaasAU/stack/pull/889) [`b9b9357`](https://github.com/OpenSaasAU/stack/commit/b9b935719774b01a81cfd2082387b76806c1a484) Thanks [@borisno2](https://github.com/borisno2)! - Fix `getSessionFromAuth` to project `sessionFields` from the _resolved_ better-auth session instead of only its `user` sub-object. A `customSession` plugin's replaced shape with no `user` key is now correctly treated as a signed-in session (never misreported as anonymous), and a session-only field (e.g. the admin plugin's `impersonatedBy`) is now resolvable. Errors from the underlying session lookup now propagate instead of silently becoming `null`, and a `sessionFields` entry that can't be resolved is omitted and logs a warning (once per field, per process) instead of vanishing silently.
+
+  The scaffolded `getSession()` — the CLI feature generator's `lib/auth.ts` template, and `examples/starter-auth`/`examples/auth-demo` — now call this single shared helper, reading `sessionFields` from the resolved config at runtime instead of baking a field list in at generation time. `examples/auth-demo`'s `getSession()` also now correctly returns `null` for an anonymous visitor (previously returned a truthy object of `undefined` values).
+
+  ```typescript
+  authPlugin({ sessionFields: ['userId', 'email', 'name', 'role'] })
+  ```
+
+  ```typescript
+  // lib/auth.ts
+  export async function getSession() {
+    const resolvedConfig = await config
+    const authConfig = resolvedConfig._pluginData?.auth as NormalizedAuthConfig | undefined
+    const sessionFields = authConfig?.sessionFields ?? ['userId', 'email', 'name']
+    return getSessionFromAuth(auth, sessionFields, await headers())
+  }
+  ```
+
+## 0.37.0
+
+### Minor Changes
+
+- [#872](https://github.com/OpenSaasAU/stack/pull/872) [`17acf04`](https://github.com/OpenSaasAU/stack/commit/17acf046b494da184c2b77434a7b4d3400ca32f2) Thanks [@borisno2](https://github.com/borisno2)! - `createAuth()` now forwards `AuthConfig` options it previously normalized but silently dropped: `emailAndPassword.minPasswordLength`, `passwordReset.enabled`/`tokenExpiration` (wired to better-auth's `sendResetPassword`), and `emailVerification.enabled`/`sendOnSignUp`/`tokenExpiration` (wired to `sendVerificationEmail`).
+
+  The stack does not wrap these email callbacks in any way — `emailAndPassword.sendResetPassword` and `emailVerification.sendVerificationEmail` are better-auth's own option shape, forwarded straight through, so an app configures them exactly as it would when calling `betterAuth()` directly:
+
+  ```typescript
+  authPlugin({
+    emailAndPassword: {
+      enabled: true,
+      sendResetPassword: async ({ user, url }) => {
+        await resend.emails.send({
+          to: user.email,
+          subject: 'Reset your password',
+          html: `<a href="${url}">Reset your password</a>`,
+        })
+      },
+    },
+    emailVerification: {
+      enabled: true,
+      sendVerificationEmail: async ({ user, url }) => {
+        await resend.emails.send({
+          to: user.email,
+          subject: 'Verify your email',
+          html: `<a href="${url}">Verify your email</a>`,
+        })
+      },
+    },
+  })
+  ```
+
+  If not provided, reset/verification emails are logged to console instead of sent — apps relying on the previous no-op behavior (verification/reset emails silently not sending) will start sending real emails once `emailVerification`/`passwordReset` are enabled and these callbacks are configured.
+
+  Two related fixes, both changing existing behavior:
+
+  - `session.updateAge` is retyped from `boolean` to `number | false` — the number of seconds between session refreshes, passed straight through to better-auth's own `session.updateAge` instead of being computed as `expiresIn / 10`. The default changes from `true` to `86400` (1 day), matching better-auth's own default. Update any `updateAge: true` config to a duration in seconds (e.g. `86400`). `updateAge: false` now correctly maps to better-auth's `disableSessionRefresh: true` (previously it mapped to `updateAge: 0`, which better-auth treats as "refresh on every request" — the opposite of disabling refresh).
+  - `getSessionFromAuth(auth, sessionFields, headers)` gains a required third `headers: Headers` parameter. Previously it always called `auth.api.getSession({ headers: new Headers() })`, an empty header set that could never resolve a session cookie, so the function always returned `null`. Callers must now pass the request's real headers (e.g. Next.js `await headers()`).
+
+  Setting `emailAndPassword.requireConfirmation` (while `emailAndPassword.enabled` is true) now logs a `console.warn` — it has no better-auth server-side equivalent (it's a UI-only "confirm password" concern). Pass `requirePasswordConfirmation` directly to `<SignUpForm>`/`<ResetPasswordForm>` instead. Similarly, `passwordReset.enabled` now warns if `emailAndPassword.enabled` is false, since password reset has no effect without a password-based account.
+
+- [#871](https://github.com/OpenSaasAU/stack/pull/871) [`06375ca`](https://github.com/OpenSaasAU/stack/commit/06375cad571677e92bfe84c35ff55240f3546a1f) Thanks [@{](https://github.com/{)! - Add a per-model `tableName` option, independent of `modelName`, so a renamed Auth list key can still adopt a differently-named live table — most commonly better-auth's own default lowercase table names (`user`, `session`, `account`, `verification`).
+
+  ```typescript
+  authPlugin({
+   modelName: 'AuthUser', tableName: 'user' },
+    session: { modelName: 'AuthSession', tableName: 'session' },
+  })
+  ```
+
+  `adoptBetterAuthTables()` gains matching `useBetterAuthTableNames` and `tableNames` options:
+
+  ```typescript
+  adoptBetterAuthTables({ useBetterAuthTableNames: true })
+  // or explicitly:
+  adoptBetterAuthTables({ tableNames: { user: 'user', session: 'session' } })
+  ```
+
+  With no `tableName` set, behaviour is unchanged: the table name still follows `modelName` when it differs from the better-auth default, otherwise no `@@map` is emitted.
+
+- [#874](https://github.com/OpenSaasAU/stack/pull/874) [`7ef9dbc`](https://github.com/OpenSaasAU/stack/commit/7ef9dbc2f94cc4e7ab831ecafb3ef65159a3c55e) Thanks [@borisno2](https://github.com/borisno2)! - Add a `betterAuthOptions` escape hatch on `AuthConfig` for better-auth options the stack doesn't model, plus an exported `buildBetterAuthOptions()` builder for apps that still need to hand-wire their own `betterAuth()` instance.
+
+  `betterAuthOptions` is deep-merged onto the options `createAuth()` builds, applied last — a plain-object value merges recursively alongside sibling keys the stack already set (e.g. `session: { cookieCache }` doesn't clobber `session.expiresIn`), and wins on any genuine key collision:
+
+  ```typescript
+  authPlugin({
+    betterAuthOptions: {
+      databaseHooks: { user: { create: { after: syncDomainUser } } },
+      session: { cookieCache: { enabled: true, maxAge: 300 } },
+      verification: { storeIdentifier: 'hashed' },
+      baseURL: process.env.BETTER_AUTH_URL,
+    },
+  })
+  ```
+
+  `database`, `plugins`, and `additionalFields` under `user`/`session`/`account`/`verification` are rejected — they already have dedicated seams (`db` config, `betterAuthPlugins`), or have schema consequences a passthrough can't also apply to the generated Prisma schema.
+
+  `buildBetterAuthOptions(config, context)` returns the exact same options object `createAuth()` uses, for apps that need a resolved `betterAuth()` instance rather than `createAuth()`'s lazy proxy:
+
+  ```typescript
+  import { betterAuth } from 'better-auth'
+  import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
+
+  export const auth = betterAuth({
+    ...(await buildBetterAuthOptions(config, rawOpensaasContext)),
+    databaseHooks: { user: { create: { after: syncDomainUser } } },
+  })
+  ```
+
+- [#870](https://github.com/OpenSaasAU/stack/pull/870) [`7b6189f`](https://github.com/OpenSaasAU/stack/commit/7b6189fa60119a45082ba62dd71d915d93de529c) Thanks [@relationship({](https://github.com/relationship({)! - A relationship field's foreign key can now be declared non-nullable via `db.isNullable: false` — the generated FK column and its relation field lose their `?` together. Omitting the option leaves every existing relationship unchanged (still nullable by default).
+
+  ```typescript
+
+    ref: 'User.sessions',
+    db: { isNullable: false },
+  })
+  // Generates: userId String  (was String?)
+  //            user   User    @relation(...)  (was User?)
+  ```
+
+  `@opensaas/stack-auth`'s derived Auth lists now use this to match better-auth's own Prisma schema: `Session.expiresAt`, `Verification.expiresAt`, and the `Session.user`/`Account.user` foreign keys generate as required instead of nullable.
+
+  **Migration note:** this changes the generated schema for existing greenfield apps. Running `opensaas generate` followed by `prisma db push`/`prisma migrate dev` will produce a migration that adds `NOT NULL` to `Session.expiresAt`, `Verification.expiresAt`, `Session.userId`, and `Account.userId`. Since better-auth's own adapter always writes these columns, no existing row should violate the new constraint — but back up production data before applying, as with any schema migration.
+
+### Patch Changes
+
+- [#867](https://github.com/OpenSaasAU/stack/pull/867) [`43b4d17`](https://github.com/OpenSaasAU/stack/commit/43b4d1738340f05b1cf8bec3315927b3004816dd) Thanks [@borisno2](https://github.com/borisno2)! - Fix a better-auth plugin's schema extension of a base model (`user`/`session`/`account`/`verification`) silently dropping the derived Auth list's `db` (`map`/`schema`/`timestamps`) and `access` config.
+
 ## 0.36.0
 
 ## 0.35.0

package/CLAUDE.md

@@ -28,7 +28,8 @@ Auto-generated lists:
 
 ### Server (`src/server/index.ts`)
 
-- `createAuth(config, rawContext?)` - Creates Better-auth instance with MCP plugin support
+- `createAuth(config, rawContext?, betterAuthPlugins?)` - Creates Better-auth instance with MCP plugin support
+- `buildBetterAuthOptions(config, rawContext?, betterAuthPlugins?)` - Returns the same `BetterAuthOptions` `createAuth()` builds, without constructing an instance — for apps that need to hand-wire their own `betterAuth()`. The optional third argument (the app's own `betterAuthPlugins` array) makes the return type carry that literal plugin tuple instead of the widened array type — see "Typed `auth.api.*` reads" below.
 - Returns `{ handler, signIn, signOut, ... }` - Better-auth methods
 
 ### Client (`src/client/index.ts`)
@@ -71,13 +72,16 @@ developer writes — not hardcoded. The pure derivation lives in
 `src/config/derive-auth-lists.ts` (`deriveAuthLists`), which `getAuthLists`
 and the plugin's add-vs-extend logic consume:
 
-- per-model `modelName` → list key + table `@@map`
+- per-model `modelName` → list key (and Prisma model name)
+- per-model `tableName` → table `@@map`, **independent of `modelName`**
+  (defaults to `modelName` when it differs from the better-auth default,
+  otherwise unset — i.e. unchanged output when `tableName` isn't set)
 - per-model `fields` (better-auth field → column) → field-level `@map`
 - the `userId` column override → the `user` relationship foreign-key `@map`
 - relationship refs between the Auth lists follow the derived keys
   (e.g. `Session.user → AuthUser.sessions`)
 
-With no `modelName`/`fields` overrides the output is unchanged
+With no `modelName`/`tableName`/`fields` overrides the output is unchanged
 (`User`/`Session`/`Account`/`Verification`, original field shapes, no `@@map`).
 
 ```typescript
@@ -89,6 +93,15 @@ authPlugin({
 // Adds AuthUser/AuthSession/... and leaves an app's own `User` untouched.
 ```
 
+```typescript
+// modelName sets the list key; tableName independently pins the live table —
+// e.g. a prefixed list key adopting better-auth's own default lowercase table.
+authPlugin({
+  user: { modelName: 'AuthUser', tableName: 'user' },
+  session: { modelName: 'AuthSession', tableName: 'session' },
+})
+```
+
 Because the plugin only ever adds/extends its **derived** keys, an app's own
 domain `User` (a different model from the better-auth user) is never extended
 or overwritten when the user model is renamed. The runtime `getUser`/
@@ -164,10 +177,10 @@ How it wires up (Postgres multi-schema):
 
 `adoptBetterAuthTables()` (`src/config/adopt-better-auth-tables.ts`) is a thin
 recipe that returns the `AuthConfig` adoption knobs — the plugin-level `schema`
-plus a per-model `modelName` (and optional column `fields` maps) — preset to the
-conventions of a standard separate-schema better-auth install. It ties together
-the keys/field derivation and schema placement so a migrator doesn't rebuild the
-config by hand. Spread it into `authPlugin`:
+plus a per-model `modelName` (and optional column `fields`/`tableName` maps) —
+preset to the conventions of a standard separate-schema better-auth install. It
+ties together the keys/field derivation and schema placement so a migrator
+doesn't rebuild the config by hand. Spread it into `authPlugin`:
 
 ```typescript
 import { authPlugin, adoptBetterAuthTables } from '@opensaas/stack-auth'
@@ -176,7 +189,23 @@ authPlugin({
   ...adoptBetterAuthTables(), // schema: 'auth', AuthUser/AuthSession/AuthAccount/AuthVerification
   emailAndPassword: { enabled: true },
 })
-// Options: adoptBetterAuthTables({ schema, modelNamePrefix, fields })
+// Options: adoptBetterAuthTables({ schema, modelNamePrefix, fields, useBetterAuthTableNames, tableNames })
+```
+
+The most common adoption shape is a project that ran better-auth **before**
+Stack, so its live tables are still better-auth's own default lowercase names
+(`user`/`session`/`account`/`verification`) even though the derived list keys
+need an `Auth` prefix to avoid colliding with the app's own domain `User`.
+`useBetterAuthTableNames: true` sets every model's `tableName` to that
+default; the per-model `tableNames` map is the escape hatch for a mix (it
+wins over `useBetterAuthTableNames` for any model it names):
+
+```typescript
+authPlugin({
+  ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+  // → AuthUser/AuthSession/AuthAccount/AuthVerification list keys,
+  //   @@map("user")/@@map("session")/@@map("account")/@@map("verification")
+})
 ```
 
 It is pure config (no side effects): everything it sets can also be written
@@ -206,7 +235,8 @@ const context = createContext(config, prisma, session)
 
 ### Session Fields Configuration
 
-Control which User fields appear in session:
+`sessionFields` describes a **flattened projection** of the resolved better-auth session, not
+the session's own shape:
 
 ```typescript
 authPlugin({ sessionFields: ['userId', 'email', 'name', 'role'] })
@@ -218,6 +248,15 @@ access: {
 }
 ```
 
+`getSessionFromAuth()` (`@opensaas/stack-auth/server`) is the single implementation of this
+projection — the scaffolded `getSession()` calls it with `sessionFields` read from the resolved
+config at runtime. Each name resolves against a fixed precedence (a top-level key on the
+resolved session, then `user`, then `session`), with `userId` special-cased to the user's `id`.
+A `customSession` better-auth plugin fully replaces the resolved shape and can nest fields
+anywhere; reconciling that against `sessionFields` is the app's job — an unresolvable name is
+omitted and warns once (per field, per process) rather than silently becoming `undefined`. See
+the `sessionFields` reference (`docs/content/reference/auth.md`) for the full contract.
+
 ### Session Type Safety
 
 To get autocomplete and type safety for session fields, use module augmentation:
@@ -294,6 +333,111 @@ authPlugin({
 })
 ```
 
+### Escape hatch for unmodelled better-auth options (`betterAuthOptions`)
+
+`AuthConfig` models a deliberately closed set of better-auth options. For
+anything the stack doesn't model — database hooks, `session.cookieCache`,
+`baseURL`, `verification.storeIdentifier`, and so on — pass it through
+`betterAuthOptions`, typed as better-auth's own `BetterAuthOptions` so it
+tracks better-auth's surface without the stack re-declaring it:
+
+```typescript
+authPlugin({
+  betterAuthOptions: {
+    databaseHooks: { user: { create: { after: syncDomainUser } } },
+    session: { cookieCache: { enabled: true, maxAge: 300 } },
+    verification: { storeIdentifier: 'hashed' },
+    baseURL: process.env.BETTER_AUTH_URL,
+  },
+})
+```
+
+`createAuth()` (`src/server/index.ts`) deep-merges `betterAuthOptions` onto
+the options it builds from the rest of `AuthConfig`, applied **last**:
+plain-object values merge recursively per key (so `session: { cookieCache }`
+lands alongside the stack's own `session.expiresIn`/`updateAge` instead of
+replacing the whole `session` block), arrays and other value types replace
+outright, and `betterAuthOptions` wins on any genuine key collision. The
+merge and the option-building it merges onto both live in
+`buildBetterAuthOptions()`, the single place `createAuth()` and the exported
+builder share — they cannot drift from each other because `createAuth()`
+calls it directly rather than reimplementing it.
+
+`database` and `plugins` are rejected outright (`assertNoUnsupportedPassthroughKeys`
+in `src/server/index.ts`): they already have dedicated seams (`db` in the
+stack config, and `betterAuthPlugins` respectively), and accepting them here
+would create two unranked ways to set the same thing — worse for `plugins`,
+since the stack must append `nextCookies()` last (see "Auth forms submit
+through server actions" below). `additionalFields` under `user`/`session`/
+`account`/`verification` is rejected too — it adds columns with no
+corresponding change to the generated Prisma schema, which is exactly the
+silent-divergence failure mode this passthrough exists to avoid elsewhere.
+Add fields to the derived list instead: `extendUserList` for the user model,
+or declare the list yourself in your own `lists` config for the others (the
+auth plugin's `addList`-vs-`extendList` logic — see "Deriving Auth lists from
+better-auth config" above — merges in field additions for any list matching
+one of its derived keys).
+
+### Hand-wiring `betterAuth()` from the stack config (`buildBetterAuthOptions`)
+
+An app that needs a resolved `betterAuth()` instance at module-init time
+(rather than `createAuth()`'s lazy proxy) can derive its options from the
+stack config instead of duplicating them:
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { buildBetterAuthOptions } from '@opensaas/stack-auth/server'
+
+export const auth = betterAuth({
+  ...(await buildBetterAuthOptions(config, rawOpensaasContext)),
+  databaseHooks: { user: { create: { after: syncDomainUser } } }, // not yet in betterAuthOptions
+})
+```
+
+This is the same async-resolve-then-construct step `createAuth()` performs
+internally, exported standalone — see ADR-0014 and root `CLAUDE.md`'s
+"Getting the ORM client outside a request" for why `createAuth()` itself
+can't be synchronous. It gives an incremental path onto `createAuth()`: adopt
+the builder first, then fold options into `betterAuthOptions` above as the
+stack grows first-class config for them.
+
+**Typed `auth.api.*` reads.** Called with just `(config, context)`, both
+`buildBetterAuthOptions()` and `createAuth()` return the widened
+`BetterAuthOptions` / `Auth<BetterAuthOptions>` — better-auth infers plugin
+endpoints and a `customSession()`'s replaced session shape from the _literal_
+options type, so the widened form erases them (an `emailOTP()` plugin loses
+`auth.api.signInEmailOTP`; `auth.api.getSession()` falls back to `{ user,
+session }` instead of a `customSession()` shape). Both functions take the
+app's `betterAuthPlugins` array — the exact same array passed to
+`authPlugin({ betterAuthPlugins })` — as an optional third argument, and their
+return type then carries that literal tuple (plus the `nextCookies()` the
+stack always appends last) instead of the widened array type:
+
+```typescript
+export const appBetterAuthPlugins = [emailOTP({ sendVerificationOTP })] // same array passed to authPlugin({ betterAuthPlugins })
+
+export const auth = betterAuth({
+  ...(await buildBetterAuthOptions(config, rawOpensaasContext, appBetterAuthPlugins)),
+})
+// auth.api.signInEmailOTP is now typed.
+```
+
+The supplied tuple is for typing only — the plugin array used at runtime is
+always the one resolved from `authPlugin({ betterAuthPlugins })` — so both
+functions verify the supplied tuple is the same plugin instances in the same
+order as the resolved array, throwing a prefixed error naming the mismatch if
+not (`assertPluginTupleMatchesResolved` in `src/server/index.ts`). This is
+what closes the drift hole a hand-rolled re-pass of the plugin array would
+otherwise open.
+
+`createAuth()`'s lazy `Proxy` does not behave identically to a real `Auth`
+instance for every property regardless of which form you use — every access,
+including a non-function property, is surfaced through an `async` wrapper (so
+`auth.options` reads back as a `Promise`, not the plain object a real
+instance returns synchronously). Reach for `buildBetterAuthOptions()` plus
+`betterAuth()` instead when the app reads `auth.api.*` in typed code — it
+constructs a real instance and does not have this gap.
+
 ## Integration Points
 
 ### With @opensaas/stack-core

package/README.md

@@ -164,7 +164,15 @@ authPlugin({
   emailAndPassword: {
     enabled: true,
     minPasswordLength: 8,
-    requireConfirmation: true,
+    requireConfirmation: true, // UI-only — pass to <SignUpForm>/<ResetPasswordForm> directly
+    // Passed straight through to better-auth's own `emailAndPassword.sendResetPassword`
+    sendResetPassword: async ({ user, url }) => {
+      await yourEmailService.send({
+        to: user.email,
+        subject: 'Reset your password',
+        html: `<a href="${url}">Reset your password</a>`,
+      })
+    },
   },
 
   // Email verification
@@ -172,6 +180,14 @@ authPlugin({
     enabled: true,
     sendOnSignUp: true,
     tokenExpiration: 86400, // 24 hours in seconds
+    // Passed straight through to better-auth's own `emailVerification.sendVerificationEmail`
+    sendVerificationEmail: async ({ user, url }) => {
+      await yourEmailService.send({
+        to: user.email,
+        subject: 'Verify your email',
+        html: `<a href="${url}">Verify your email</a>`,
+      })
+    },
   },
 
   // Password reset
@@ -195,7 +211,7 @@ authPlugin({
   // Session configuration
   session: {
     expiresIn: 604800, // 7 days in seconds
-    updateAge: true, // Refresh session on each request
+    updateAge: 86400, // seconds between session refreshes; set `false` to disable
   },
 
   // Fields to include in session object
@@ -208,11 +224,6 @@ authPlugin({
       company: text(),
     },
   },
-
-  // Custom email sending function
-  sendEmail: async ({ to, subject, html }) => {
-    await yourEmailService.send({ to, subject, html })
-  },
 })
 ```
 

package/dist/config/adopt-better-auth-tables.d.ts

@@ -28,6 +28,22 @@
  * auth migration. The recipe never touches the application's own domain `User`:
  * its model names are `Auth`-prefixed by default and the plugin only ever
  * adds/extends its *derived* keys.
+ *
+ * The single most common adoption shape is a project that ran better-auth
+ * *before* adding Stack: its live tables are still better-auth's own default
+ * lowercase names (`user`/`session`/`account`/`verification`), even though the
+ * derived list keys need the `Auth` prefix to avoid colliding with the app's
+ * own domain `User`. Pass `useBetterAuthTableNames: true` to point every
+ * model's physical table at that default while keeping the prefixed list keys
+ * (or `tableNames` for an explicit per-model override):
+ *
+ * ```typescript
+ * authPlugin({
+ *   ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+ *   // AuthUser/AuthSession/AuthAccount/AuthVerification list keys,
+ *   // @@map("user")/@@map("session")/@@map("account")/@@map("verification")
+ * })
+ * ```
  */
 import type { AuthConfig } from './types.js';
 /**
@@ -85,6 +101,37 @@ export type AdoptBetterAuthTablesOptions = {
         account?: Record<string, string>;
         verification?: Record<string, string>;
     };
+    /**
+     * Set every model's physical table name to better-auth's own default
+     * lowercase table name (`user`, `session`, `account`, `verification`) —
+     * independent of the prefixed list key/`modelName`.
+     *
+     * This is the single most common adoption shape: a project that ran
+     * better-auth before adding the stack has exactly these tables, and the
+     * default `modelNamePrefix: 'Auth'` alone would otherwise pin the table
+     * name to the prefixed model name (`AuthUser`, ...), which `prisma migrate
+     * diff` reads as a rename against the live `user` table.
+     *
+     * Ignored for a model with an explicit entry in {@link tableNames}.
+     *
+     * @default false
+     */
+    useBetterAuthTableNames?: boolean;
+    /**
+     * Per-model explicit table name overrides, keyed by model. Takes
+     * precedence over `useBetterAuthTableNames` for that model.
+     *
+     * @example
+     * ```typescript
+     * adoptBetterAuthTables({ tableNames: { user: 'users' } })
+     * ```
+     */
+    tableNames?: {
+        user?: string;
+        session?: string;
+        account?: string;
+        verification?: string;
+    };
 };
 /**
  * The adoption-relevant slice of {@link AuthConfig}: the plugin-level `schema`

package/dist/config/adopt-better-auth-tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adopt-better-auth-tables.d.ts","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACtC,CAAA;CACF,CAAA;AAUD;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,UAAU,EACV,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,CAC3D,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,2BAA2B,CAqB7B"}
+{"version":3,"file":"adopt-better-auth-tables.d.ts","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAChC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACtC,CAAA;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;IAEjC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF,CAAA;AAkBD;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,UAAU,EACV,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,CAC3D,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,2BAA2B,CAiC7B"}

package/dist/config/adopt-better-auth-tables.js

@@ -28,6 +28,22 @@
  * auth migration. The recipe never touches the application's own domain `User`:
  * its model names are `Auth`-prefixed by default and the plugin only ever
  * adds/extends its *derived* keys.
+ *
+ * The single most common adoption shape is a project that ran better-auth
+ * *before* adding Stack: its live tables are still better-auth's own default
+ * lowercase names (`user`/`session`/`account`/`verification`), even though the
+ * derived list keys need the `Auth` prefix to avoid colliding with the app's
+ * own domain `User`. Pass `useBetterAuthTableNames: true` to point every
+ * model's physical table at that default while keeping the prefixed list keys
+ * (or `tableNames` for an explicit per-model override):
+ *
+ * ```typescript
+ * authPlugin({
+ *   ...adoptBetterAuthTables({ useBetterAuthTableNames: true }),
+ *   // AuthUser/AuthSession/AuthAccount/AuthVerification list keys,
+ *   // @@map("user")/@@map("session")/@@map("account")/@@map("verification")
+ * })
+ * ```
  */
 /** The four better-auth models and their default (unprefixed) model names. */
 const MODEL_DEFAULT_NAMES = {
@@ -36,6 +52,13 @@ const MODEL_DEFAULT_NAMES = {
     account: 'Account',
     verification: 'Verification',
 };
+/** better-auth's own default lowercase table names, per model. */
+const BETTER_AUTH_DEFAULT_TABLE_NAMES = {
+    user: 'user',
+    session: 'session',
+    account: 'account',
+    verification: 'verification',
+};
 /**
  * Build the adoption {@link AuthConfig} fragment for a pre-existing better-auth
  * installation.
@@ -48,11 +71,16 @@ const MODEL_DEFAULT_NAMES = {
  *   (and any field column maps) set to match the live tables
  */
 export function adoptBetterAuthTables(options = {}) {
-    const { schema = 'auth', modelNamePrefix = 'Auth', fields = {} } = options;
+    const { schema = 'auth', modelNamePrefix = 'Auth', fields = {}, useBetterAuthTableNames = false, tableNames = {}, } = options;
     const buildModel = (model) => {
         const config = {
             modelName: `${modelNamePrefix}${MODEL_DEFAULT_NAMES[model]}`,
         };
+        const tableName = tableNames[model] ??
+            (useBetterAuthTableNames ? BETTER_AUTH_DEFAULT_TABLE_NAMES[model] : undefined);
+        if (tableName !== undefined) {
+            config.tableName = tableName;
+        }
         const fieldMap = fields[model];
         if (fieldMap && Object.keys(fieldMap).length > 0) {
             config.fields = fieldMap;

package/dist/config/adopt-better-auth-tables.js.map

@@ -1 +1 @@
-{"version":3,"file":"adopt-better-auth-tables.js","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+DH,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG;IAC1B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;CACpB,CAAA;AAYV;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAO,GAAiC,EAAE;IAE1C,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,MAAM,GAAG,EAAE,EAAE,GAAG,OAAO,CAAA;IAE1E,MAAM,UAAU,GAAG,CAAC,KAAuC,EAAmB,EAAE;QAC9E,MAAM,MAAM,GAAoB;YAC9B,SAAS,EAAE,GAAG,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE;SAC7D,CAAA;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC9B,IAAI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAA;QAC1B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO;QACL,MAAM;QACN,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;QACxB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC;KACzC,CAAA;AACH,CAAC"}
+{"version":3,"file":"adopt-better-auth-tables.js","sourceRoot":"","sources":["../../src/config/adopt-better-auth-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAgGH,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG;IAC1B,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;CACpB,CAAA;AAEV,kEAAkE;AAClE,MAAM,+BAA+B,GAAG;IACtC,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,YAAY,EAAE,cAAc;CACpB,CAAA;AAYV;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAO,GAAiC,EAAE;IAE1C,MAAM,EACJ,MAAM,GAAG,MAAM,EACf,eAAe,GAAG,MAAM,EACxB,MAAM,GAAG,EAAE,EACX,uBAAuB,GAAG,KAAK,EAC/B,UAAU,GAAG,EAAE,GAChB,GAAG,OAAO,CAAA;IAEX,MAAM,UAAU,GAAG,CAAC,KAAuC,EAAmB,EAAE;QAC9E,MAAM,MAAM,GAAoB;YAC9B,SAAS,EAAE,GAAG,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE;SAC7D,CAAA;QACD,MAAM,SAAS,GACb,UAAU,CAAC,KAAK,CAAC;YACjB,CAAC,uBAAuB,CAAC,CAAC,CAAC,+BAA+B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAChF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,CAAC,SAAS,GAAG,SAAS,CAAA;QAC9B,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC9B,IAAI,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAA;QAC1B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO;QACL,MAAM;QACN,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;QACxB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC;QAC9B,YAAY,EAAE,UAAU,CAAC,cAAc,CAAC;KACzC,CAAA;AACH,CAAC"}

package/dist/config/derive-auth-lists.d.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`)

package/dist/config/derive-auth-lists.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-auth-lists.d.ts","sourceRoot":"","sources":["../../src/config/derive-auth-lists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAA6B,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAanG;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oDAAoD;IACpD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,kEAAkE;IAElE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;CACvC,CAAA;AAyMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,GAAE,oBAAyB,EACrC,YAAY,GAAE,gBAAqB,GAClC,gBAAgB,CAiBlB"}
+{"version":3,"file":"derive-auth-lists.d.ts","sourceRoot":"","sources":["../../src/config/derive-auth-lists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAA6B,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEnG;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oDAAoD;IACpD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,kEAAkE;IAElE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;CACvC,CAAA;AAiND;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,GAAE,oBAAyB,EACrC,YAAY,GAAE,gBAAqB,GAClC,gBAAgB,CAiBlB"}